diff --git a/Browser/browser.py b/Browser/browser.py index 73bfa15a8..1c296910f 100755 --- a/Browser/browser.py +++ b/Browser/browser.py @@ -466,27 +466,90 @@ def __init__( # noqa: PLR0915 timeout: timedelta = timedelta(seconds=10), tracing_group_mode: TracingGroupMode = TracingGroupMode.Full, ): - """Browser library can be taken into use with optional arguments: - - | =Argument= | =Description= | - | ``auto_closing_level`` | Configure context and page automatic closing. Default is ``TEST``, for more details, see `AutoClosingLevel` | - | ``auto_delete_passed_tracing`` | If ``auto_closing_level`` is set to ``SUITE`` or ``TEST`` and ``tracing`` of `New Context` active, traces of passed tests or suites, depending on the context scope, not be saved. Also temp files will all be deleted after the whole execution ends. | - | ``enable_playwright_debug`` | Enable low level debug information from the playwright to playwright-log.txt file. For more details, see `PlaywrightLogTypes`. | - | ``enable_presenter_mode`` | Automatic highlights the interacted components, slowMo and a small pause at the end. Can be enabled by giving True or can be customized by giving a dictionary: `{"duration": "2 seconds", "width": "2px", "style": "dotted", "color": "blue"}` Where `duration` is time format in Robot Framework format, defaults to 2 seconds. `width` is width of the marker in pixels, defaults the `2px`. `style` is the style of border, defaults to `dotted`. `color` is the color of the marker, defaults to `blue`. By default, the call banner keyword is also enabled unless explicitly disabled. | - | ``external_browser_executable`` | Dict mapping name of browser to path of executable of a browser. Will make opening new browsers of the given type use the set executablePath. Currently only configuring of `chromium` to a separate executable (chrome, chromium and Edge executables all work with recent versions) works. | - | ``highlight_on_failure`` | If set to ``True``, will highlight the element in the screenshot when a keyword fails, by highlighting the selector used in the failed keyword. If set to ``False``, will not highlight the element. | - | ``jsextension`` | Path to JavaScript modules exposed as extra keywords. The modules must be in CommonJS format; exported functions become keywords and an ``fn.rfdoc`` string becomes a keyword's documentation. The argument names ``page``, ``context``, ``browser``, ``logger`` and ``playwright`` are filled in by the library rather than taken from the keyword call. Can be a single path, a comma-separated list of paths or a real list of strings. See https://robotframework-browser.org/docs/extending/javascript-extensions | - | ``language`` | Defines language which is used to translate keyword names and documentation. | - | ``playwright_process_host`` | Hostname / Host address which should be used when spawning the Playwright process. Defaults to 127.0.0.1. | - | ``playwright_process_port`` | Experimental reusing of playwright process. ``playwright_process_port`` is preferred over environment variable ``ROBOT_FRAMEWORK_BROWSER_NODE_PORT``. See `Experimental: Re-using same node process` for more details. | - | ``plugins`` | Allows extending the Browser library with external Python classes, which can add keywords and modify some internal behaviour without forking the library. Can be a single class/module, a comma-separated list or a real list of strings. See https://robotframework-browser.org/docs/extending/python-plugins | - | ``retry_assertions_for`` | Timeout for retrying assertions on keywords before failing the keywords. This timeout starts counting from the first failure. Global ``timeout`` will still be in effect. This allows stopping execution faster to assertion failure when element is found fast. | - | ``run_on_failure`` | Sets the keyword to execute in case of a failing Browser keyword. It can be the name of any keyword. If the keyword has arguments those must be separated with two spaces for example ``My keyword \\ arg1 \\ arg2``. If no extra action should be done after a failure, set it to ``None`` or any other robot falsy value. Run on failure is not applied when library methods are executed directly from Python. | - | ``selector_prefix`` | Prefix for all selectors. This is useful when you need to use add an iframe selector before each selector. | - | ``show_keyword_call_banner`` | If set to ``True``, will show a banner with the keyword name and arguments before the keyword is executed at the bottom of the page. If set to ``False``, will not show the banner. If set to None, which is the default, will show the banner only if the presenter mode is enabled. `Get Page Source` and `Take Screenshot` will not show the banner, because that could negatively affect your test cases/tasks. This feature may be super helpful when you are debugging your tests and using tracing from `New Context` or `Video recording` features. | - | ``strict`` | If keyword selector points multiple elements and keywords should interact with one element, keyword will fail if ``strict`` mode is true. Strict mode can be changed individually in keywords or by ``Set Strict Mode`` keyword. | - | ``timeout`` | Timeout for keywords that operate on elements. The keywords will wait for this time for the element to appear into the page. Defaults to "10s" => 10 seconds. | - | ``tracing_group_mode`` | Defines how Robot Framework keyword calls are logged in Playwright trace log. Default is `Full`. For more details, see `TracingGroupMode`. | + """Browser library can be taken into use with optional arguments. + + *Arguments:* + - ``_``: Positional arguments are ignored. All arguments must be passed as named arguments. + - ``auto_closing_level``: Configure context and page automatic closing. + Default is ``TEST``, for more details, see `AutoClosingLevel` + - ``auto_delete_passed_tracing``: If ``auto_closing_level`` is set to + ``SUITE`` or ``TEST`` and ``tracing`` of `New Context` active, traces of + passed tests or suites, depending on the context scope, not be saved. + Also temp files will all be deleted after the whole execution ends. + - ``enable_playwright_debug``: Enable low level debug information from the + playwright to playwright-log.txt file. For more details, see + `PlaywrightLogTypes`. + - ``enable_presenter_mode``: Automatic highlights the interacted components, + slowMo and a small pause at the end. Can be enabled by giving True or + can be customized by giving a dictionary: ``{"duration": "2 seconds", + "width": "2px", "style": "dotted", "color": "blue"}`` Where `duration` is + time format in Robot Framework format, defaults to 2 seconds. `width` is + width of the marker in pixels, defaults the ``2px``. ``style`` is the style + of border, defaults to ``dotted``. ``color`` is the color of the marker, + defaults to ``blue``. By default, the call banner keyword is also enabled + unless explicitly disabled. + - ``external_browser_executable``: Dict mapping name of browser to path of + executable of a browser. Will make opening new browsers of the given + type use the set executablePath. Currently only configuring of + ``chromium`` to a separate executable (chrome, chromium and Edge + executables all work with recent versions) works. + - ``highlight_on_failure``: If set to ``True``, will highlight the element in + the screenshot when a keyword fails, by highlighting the selector used + in the failed keyword. If set to ``False``, will not highlight the + element. + - ``jsextension``: Path to JavaScript modules exposed as extra keywords. The + modules must be in CommonJS format; exported functions become keywords + and an ``fn.rfdoc`` string becomes a keyword's documentation. The + argument names ``page``, ``context``, ``browser``, ``logger`` and + ``playwright`` are filled in by the library rather than taken from the + keyword call. Can be a single path, a comma-separated list of paths or a + real list of strings. See + https://robotframework-browser.org/docs/extending/javascript-extensions + - ``language``: Defines language which is used to translate keyword names and + documentation. + - ``playwright_process_host``: Hostname / Host address which should be used + when spawning the Playwright process. Defaults to 127.0.0.1. + - ``playwright_process_port``: Experimental reusing of playwright process. + ``playwright_process_port`` is preferred over environment variable + ``ROBOT_FRAMEWORK_BROWSER_NODE_PORT``. See `Experimental: Re-using same + node process` for more details. + - ``plugins``: Allows extending the Browser library with external Python + classes, which can add keywords and modify some internal behaviour + without forking the library. Can be a single class/module, a + comma-separated list or a real list of strings. See + https://robotframework-browser.org/docs/extending/python-plugins + - ``retry_assertions_for``: Timeout for retrying assertions on keywords before + failing the keywords. This timeout starts counting from the first + failure. Global ``timeout`` will still be in effect. This allows + stopping execution faster to assertion failure when element is found + fast. + - ``run_on_failure``: Sets the keyword to execute in case of a failing Browser + keyword. It can be the name of any keyword. If the keyword has arguments + those must be separated with two spaces for example ``My keyword \\ arg1 + \\ arg2``. If no extra action should be done after a failure, set it to + ``None`` or any other robot falsy value. Run on failure is not applied + when library methods are executed directly from Python. + - ``selector_prefix``: Prefix for all selectors. This is useful when you need + to use add an iframe selector before each selector. + - ``show_keyword_call_banner``: If set to ``True``, will show a banner with + the keyword name and arguments before the keyword is executed at the + bottom of the page. If set to ``False``, will not show the banner. If + set to None, which is the default, will show the banner only if the + presenter mode is enabled. `Get Page Source` and `Take Screenshot` will + not show the banner, because that could negatively affect your test + cases/tasks. This feature may be super helpful when you are debugging + your tests and using tracing from `New Context` or `Video recording` + features. + - ``strict``: If keyword selector points multiple elements and keywords should + interact with one element, keyword will fail if ``strict`` mode is true. + Strict mode can be changed individually in keywords or by ``Set Strict + Mode`` keyword. + - ``timeout``: Timeout for keywords that operate on elements. The keywords + will wait for this time for the element to appear into the page. + Defaults to "10s" => 10 seconds. + - ``tracing_group_mode``: Defines how Robot Framework keyword calls are logged + in Playwright trace log. Default is ``Full``. + """ if _: raise ValueError("Browser library does not accept positional arguments.") diff --git a/Browser/keywords/assertion_formatter.py b/Browser/keywords/assertion_formatter.py index b2b170867..ffe7ea7bd 100644 --- a/Browser/keywords/assertion_formatter.py +++ b/Browser/keywords/assertion_formatter.py @@ -81,9 +81,16 @@ def set_assertion_formatters( ) -> dict[str, list[str]]: """Set keywords formatters for assertions. - | =Arguments= | =Description= | - | ``formatters`` | Dictionary of keywords and formatters, where the key is the name of the keyword where the formatters are applied. The dictionary value is a list of formatters which are applied. Formatters for a defined keyword are always overwritten. An empty list will clear all formatters for the keyword. If ``formatters`` is an empty dictionary, then all formatters are cleared from all keywords, in the Global scope, regardless of the ``scope`` argument. | - | ``scope`` | Defines the lifetime of the formatter, possible values are Global, Suite and Test. | + *Arguments:* + - ``formatters``: Dictionary of keywords and formatters, where the key is the + name of the keyword where the formatters are applied. The dictionary + value is a list of formatters which are applied. Formatters for a + defined keyword are always overwritten. An empty list will clear all + formatters for the keyword. If ``formatters`` is an empty dictionary, + then all formatters are cleared from all keywords, in the Global scope, + regardless of the ``scope`` argument. + - ``scope``: Defines the lifetime of the formatter, possible values are + Global, Suite and Test. Returns the formatters which were in use before this keyword was called. Formatters defined as lambda functions are not included in the returned value. diff --git a/Browser/keywords/browser_control.py b/Browser/keywords/browser_control.py index 1bc87c0b7..5772b5ef7 100644 --- a/Browser/keywords/browser_control.py +++ b/Browser/keywords/browser_control.py @@ -77,10 +77,18 @@ def go_to( ): """Navigates to the given ``url``. - | =Arguments= | =Description= | - | ``url`` | URL to be navigated to. | - | ``timeout`` | Time to wait for the page to load. If not defined, the library default timeout is used. | - | ``wait_until`` | When to consider the operation succeeded, defaults to ``load``. The event can be either: ``domcontentloaded`` - consider the operation to be finished when the DOMContentLoaded event is fired. ``load`` - consider the operation to be finished when the load event is fired. ``networkidle`` - consider the operation to be finished when there are no network connections for at least 500 ms. ``commit`` - consider the operation to be finished when the network response is received and the document started loading. | + *Arguments:* + - ``url``: URL to be navigated to. + - ``timeout``: Time to wait for the page to load. If not defined, the library + default timeout is used. + - ``wait_until``: When to consider the operation succeeded, defaults to + ``load``. The event can be either: ``domcontentloaded`` - consider the + operation to be finished when the DOMContentLoaded event is fired. + ``load`` - consider the operation to be finished when the load event is + fired. ``networkidle`` - consider the operation to be finished when + there are no network connections for at least 500 ms. ``commit`` - + consider the operation to be finished when the network response is + received and the document started loading. Returns the HTTP status code of the navigation request as an integer, or 0 if no response was received. @@ -155,22 +163,66 @@ def take_screenshot( ) -> str | bytes | Path | None: """Takes a screenshot of the current window or element and saves it to disk. - | =Arguments= | =Description= | - | ``filename`` | Filename into which to save. The file will be saved into the Robot Framework ${OUTPUTDIR}/browser/screenshot directory by default, but it can be overwritten by providing a custom path or filename. String ``{index}`` in the filename will be replaced with a rolling number. Use this to not overwrite filenames. If filename equals to UUID (case insensitive), then the filename is created by Python uuid; https://docs.python.org/3/library/uuid.html. If filename equals to EMBED (case insensitive) or ${NONE}, then the screenshot is embedded as a Base64 image into the log.html. The image is saved temporarily to the disk and a warning is displayed if removing the temporary file fails. The ${OUTPUTDIR}/browser/screenshot directory is removed at the first suite startup. | - | ``selector`` | Take a screenshot of the element matched by selector. See the `Finding elements` section for details about the selectors. If not provided, take a screenshot of the current viewport. | - | ``crop`` | Crops the taken screenshot to the given box. It takes the same dictionary as returned from `Get BoundingBox`. Cropping only works on a page screenshot, so when no selector is given. | - | ``disableAnimations`` | When set to ``True``, stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration: - finite animations are fast-forwarded to completion, so they'll fire the transitionend event. - infinite animations are cancelled to initial state, and then played over after the screenshot. | - | ``fileType`` | ``png`` or ``jpeg``. Specifies the screenshot type, defaults to ``png``. | - | ``fullPage`` | When ``True``, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to ``False``. | - | ``highlight_selector`` | Highlights elements while taking the screenshot. Highlight method is ``playwright``. This highlighting also automatically happens if the Robot Framework variable ``${ROBOT_FRAMEWORK_BROWSER_FAILING_SELECTOR}`` is set to a selector string and is available on page. This is the case if ``highlight_on_failure`` has been set to ``True`` when importing Browser library. | - | ``log_screenshot`` | When set to ``False`` the screenshot is taken but not logged into log.html. | - | ``mask`` | Specify selectors that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box ``#FF00FF`` that completely covers their bounding box. The argument can take a single selector string or a list of selector strings if multiple different elements should be masked. | - | ``maskColor`` | Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF. | - | ``omitBackground`` | Hides the default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. | - | ``quality`` | The quality of the image, between 0-100. Not applicable to png images. | - | ``scale`` | ``css`` or ``device``. ``css`` will reduce the image size and ``device`` keeps the image in its original size. Defaults to ``device``. | - | ``return_as`` | Defines what this keyword returns. Possible values are documented in `ScreenshotReturnType`. It can be either a path to the screenshot file as string or Path object, or the image data as bytes or base64 encoded string. When the screenshot is embedded into the log, ``path_string`` returns the string ``EMBED``. | - | ``timeout`` | Maximum time how long taking the screenshot can last, defaults to the library timeout. Supports Robot Framework time format, like 10s or 1 min, pass 0 to disable the timeout. The default value can be changed by using the `Set Browser Timeout` keyword. | + *Arguments:* + - ``filename``: Filename into which to save. The file will be saved into the + Robot Framework ${OUTPUTDIR}/browser/screenshot directory by default, + but it can be overwritten by providing a custom path or filename. String + ``{index}`` in the filename will be replaced with a rolling number. Use + this to not overwrite filenames. If filename equals to UUID (case + insensitive), then the filename is created by Python uuid; + https://docs.python.org/3/library/uuid.html. If filename equals to EMBED + (case insensitive) or ${NONE}, then the screenshot is embedded as a + Base64 image into the log.html. The image is saved temporarily to the + disk and a warning is displayed if removing the temporary file fails. + The ${OUTPUTDIR}/browser/screenshot directory is removed at the first + suite startup. + - ``selector``: Take a screenshot of the element matched by selector. See the + `Finding elements` section for details about the selectors. If not + provided, take a screenshot of the current viewport. + - ``crop``: Crops the taken screenshot to the given box. It takes the same + dictionary as returned from `Get BoundingBox`. Cropping only works on a + page screenshot, so when no selector is given. + - ``disableAnimations``: When set to ``True``, stops CSS animations, CSS + transitions and Web Animations. Animations get different treatment + depending on their duration: - finite animations are fast-forwarded to + completion, so they'll fire the transitionend event. - infinite + animations are cancelled to initial state, and then played over after + the screenshot. + - ``fileType``: ``png`` or ``jpeg``. Specifies the screenshot type, defaults + to ``png``. + - ``fullPage``: When ``True``, takes a screenshot of the full scrollable page, + instead of the currently visible viewport. Defaults to ``False``. + - ``highlight_selector``: Highlights elements while taking the screenshot. + Highlight method is ``playwright``. This highlighting also automatically + happens if the Robot Framework variable + ``${ROBOT_FRAMEWORK_BROWSER_FAILING_SELECTOR}`` is set to a selector + string and is available on page. This is the case if + ``highlight_on_failure`` has been set to ``True`` when importing Browser + library. + - ``log_screenshot``: When set to ``False`` the screenshot is taken but not + logged into log.html. + - ``mask``: Specify selectors that should be masked when the screenshot is + taken. Masked elements will be overlaid with a pink box ``#FF00FF`` that + completely covers their bounding box. The argument can take a single + selector string or a list of selector strings if multiple different + elements should be masked. + - ``maskColor``: Specify the color of the overlay box for masked elements, in + CSS color format. Default color is pink #FF00FF. + - ``omitBackground``: Hides the default white background and allows capturing + screenshots with transparency. Not applicable to jpeg images. + - ``quality``: The quality of the image, between 0-100. Not applicable to png + images. + - ``scale``: ``css`` or ``device``. ``css`` will reduce the image size and + ``device`` keeps the image in its original size. Defaults to ``device``. + - ``return_as``: Defines what this keyword returns. Possible values are + documented in `ScreenshotReturnType`. It can be either a path to the + screenshot file as string or Path object, or the image data as bytes or + base64 encoded string. When the screenshot is embedded into the log, + ``path_string`` returns the string ``EMBED``. + - ``timeout``: Maximum time how long taking the screenshot can last, defaults + to the library timeout. Supports Robot Framework time format, like 10s + or 1 min, pass 0 to disable the timeout. The default value can be + changed by using the `Set Browser Timeout` keyword. Keyword uses strict mode if selector is defined. See `Finding elements` for more details about strict mode. @@ -372,9 +424,13 @@ def set_browser_timeout( ) -> str: """Sets the timeout used by most input and getter keywords. - | =Arguments= | =Description= | - | ``timeout`` | The timeout is set for the current Playwright context and for new contexts. Supports Robot Framework [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|time format]. | - | ``scope`` | Scope defines the live time of that setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope Setting` for more details. | + *Arguments:* + - ``timeout``: The timeout is set for the current Playwright context and for + new contexts. Supports Robot Framework + [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format | time format]. + - ``scope``: Scope defines the live time of that setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope Setting` for + more details. Returns the previous value of the timeout. @@ -409,9 +465,12 @@ def set_retry_assertions_for( ) -> str: """Sets the timeout used in retrying assertions when they fail. - | =Arguments= | =Description= | - | ``timeout`` | Assertion retry timeout will determine how long Browser library will retry an assertion to be true. | - | ``scope`` | Scope defines the live time of that setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more details. | + *Arguments:* + - ``timeout``: Assertion retry timeout will determine how long Browser library + will retry an assertion to be true. + - ``scope``: Scope defines the live time of that setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more + details. The other keyword `Set Browser Timeout` controls how long Playwright will wait on the node side for elements to fulfill the @@ -440,9 +499,13 @@ def set_selector_prefix( ) -> str: """Sets the prefix for all selectors in the given scope. - | =Arguments= | =Description= | - | ``prefix`` | Prefix for all selectors. Prefix and selector will be separated by a single space. Use ``${None}`` or ``${EMPTY}`` to disable the prefix. | - | ``scope`` | Scope defines the live time of that setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more details. | + *Arguments:* + - ``prefix``: Prefix for all selectors. Prefix and selector will be separated + by a single space. Use ``${None}`` or ``${EMPTY}`` to disable the + prefix. + - ``scope``: Scope defines the live time of that setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more + details. Returns the previous value of the prefix. @@ -473,9 +536,13 @@ def set_highlight_on_failure( ) -> bool: """Controls if the element is highlighted on failure. - | =Arguments= | =Description= | - | ``highlight`` | If ``True``, the element is highlighted when a screenshot is taken on failure. If ``False``, the element is not highlighted in the screenshot. | - | ``scope`` | Scope defines the live time of that setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more details. | + *Arguments:* + - ``highlight``: If ``True``, the element is highlighted when a screenshot is + taken on failure. If ``False``, the element is not highlighted in the + screenshot. + - ``scope``: Scope defines the live time of that setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more + details. Returns the previous value of the setting. @@ -500,10 +567,15 @@ def show_keyword_banner( The banner can also be controlled by an import setting of the Browser library. (see `Importing` section) - | =Arguments= | =Description= | - | ``show`` | If ``True``, the banner is shown on the page. If ``False``, the banner is not shown on the page. If ``${None}``, the banner is shown on the page only when running in presenter mode. | - | ``style`` | Additional CSS styles to be applied to the banner. These styles may override the existing ones for the banner. | - | ``scope`` | Scope defines the live time of that setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more details. | + *Arguments:* + - ``show``: If ``True``, the banner is shown on the page. If ``False``, the + banner is not shown on the page. If ``${None}``, the banner is shown on + the page only when running in presenter mode. + - ``style``: Additional CSS styles to be applied to the banner. These styles + may override the existing ones for the banner. + - ``scope``: Scope defines the live time of that setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more + details. Returns the previous settings as a dictionary with the keys ``show`` and ``style``. @@ -535,9 +607,9 @@ def set_viewport_size(self, width: int, height: int): so you should set the viewport size with `New Context` before opening the page itself. - | =Arguments= | =Description= | - | ``width`` | Sets the width in pixels. | - | ``height`` | Sets the height in pixels. | + *Arguments:* + - ``width``: Sets the width in pixels. + - ``height``: Sets the height in pixels. [https://forum.robotframework.org/t//4333|Comment >>] """ @@ -551,8 +623,9 @@ def set_viewport_size(self, width: int, height: int): def set_offline(self, offline: bool = True): """Toggles the current context's offline emulation. - | =Arguments= | =Description= | - | ``offline`` | Toggles the offline mode. Set to ``False`` to switch back to online mode. Defaults to ``True``. | + *Arguments:* + - ``offline``: Toggles the offline mode. Set to ``False`` to switch back to + online mode. Defaults to ``True``. [https://forum.robotframework.org/t//4330|Comment >>] """ @@ -570,10 +643,10 @@ def set_geolocation( The accuracy of the location must be a non-negative number and defaults to 0. When creating the context, grant the ``geolocation`` permission so that pages can read the geolocation. - | =Arguments= | =Description= | - | ``latitude`` | Latitude between -90 and 90. | - | ``longitude`` | Longitude between -180 and 180. | - | ``accuracy`` | Non-negative accuracy value. Defaults to 0. | + *Arguments:* + - ``latitude``: Latitude between -90 and 90. + - ``longitude``: Longitude between -180 and 180. + - ``accuracy``: Non-negative accuracy value. Defaults to 0. Example: | ${permissions} = Create List geolocation @@ -599,9 +672,11 @@ def reload( ): """Reloads current active page. - | =Arguments= | =Description= | - | ``timeout`` | Maximum time for the reload to succeed. If not given, the currently set browser timeout is used. | - | ``waitUntil`` | When to consider the operation succeeded, defaults to ``load``. | + *Arguments:* + - ``timeout``: Maximum time for the reload to succeed. If not given, the + currently set browser timeout is used. + - ``waitUntil``: When to consider the operation succeeded, defaults to + ``load``. ``waitUntil`` events can be either: ``domcontentloaded`` - consider the operation to be finished when the DOMContentLoaded event is fired. @@ -622,9 +697,13 @@ def reload( def grant_permissions(self, *permissions: Permission, origin: str | None = None): """Grants permissions to the current context. - | =Arguments= | =Description= | - | ``permissions`` | Permissions to grant, given as separate arguments. See `Permission` for the available values, for example ``geolocation``, ``notifications``, ``camera`` or ``microphone``. | - | ``origin`` | The origin to grant the permissions to, e.g. "https://example.com". If not given, the permissions are granted for all origins. | + *Arguments:* + - ``permissions``: Permissions to grant, given as separate arguments. See + `Permission` for the available values, for example ``geolocation``, + ``notifications``, ``camera`` or ``microphone``. + - ``origin``: The origin to grant the permissions to, e.g. + "https://example.com". If not given, the permissions are granted for all + origins. Example: | `New Context` @@ -660,8 +739,13 @@ def set_presenter_mode( When enabled, the element is scrolled into view and highlighted with a border for a while to visually show what the keyword found. - | =Arguments= | =Description= | - | ``mode`` | When set to ``True``, enables presenter mode with default settings. When set to ``False``, disables presenter mode. Can also be a dictionary containing the highlighting configuration options as defined in `HighLightElement`. Fields which are not given use their default values: ``duration`` 2 seconds, ``width`` 2px, ``style`` dotted and ``color`` blue. | + *Arguments:* + - ``mode``: When set to ``True``, enables presenter mode with default + settings. When set to ``False``, disables presenter mode. Can also be a + dictionary containing the highlighting configuration options as defined + in `HighLightElement`. Fields which are not given use their default + values: ``duration`` 2 seconds, ``width`` 2px, ``style`` dotted and + ``color`` blue. The keyword returns the previous presenter mode value, allowing you to restore it later. diff --git a/Browser/keywords/clock.py b/Browser/keywords/clock.py index 5f3d129bc..357480ef3 100644 --- a/Browser/keywords/clock.py +++ b/Browser/keywords/clock.py @@ -23,9 +23,9 @@ class Clock(LibraryComponent): def set_time(self, time: datetime, clock_type: ClockType = ClockType.install): """Sets the time of the browser's internal clock. - | =Arguments= | =Description= | - | time | The time to set. Supports Robot Framework date and time format | - | clock_type | The clock type to set. Default is ``install``. | + *Arguments:* + - ``time``: The time to set. Supports Robot Framework date and time format + - ``clock_type``: The clock type to set. Default is ``install``. ``fixed`` makes ``Date.now`` and ``new Date()`` always return the same fake time, while all timers keep running. @@ -69,8 +69,8 @@ def resume_clock(self): def pause_at(self, time: datetime): """Advances the clock by jumping forward in time and pauses it. - | =Arguments= | =Description= | - | time | The time to pause the clock at. | + *Arguments:* + - ``time``: The time to pause the clock at. Fires due timers at most once. This is equivalent to a user closing the laptop lid for a while and reopening it at the specified @@ -99,9 +99,9 @@ def advance_clock( ): """Advances the clock by a specified amount of time. - | =Arguments= | =Description= | - | time | The time to advance. Supports Robot Framework time format | - | advance_type | The type of advance. Default is ``fast_forward``. | + *Arguments:* + - ``time``: The time to advance. Supports Robot Framework time format + - ``advance_type``: The type of advance. Default is ``fast_forward``. ``run_for`` advances the clock by firing all the time-related callbacks. diff --git a/Browser/keywords/cookie.py b/Browser/keywords/cookie.py index 67e4c069b..4291620a2 100644 --- a/Browser/keywords/cookie.py +++ b/Browser/keywords/cookie.py @@ -101,17 +101,23 @@ def add_cookie( # ruff: ignore[PLR0917] ): """Adds a cookie to the currently active browser context. - - | =Arguments= | =Description= | - | ``name`` | Name of the cookie. | - | ``value`` | Given value for the cookie. | - | ``url`` | Given url for the cookie. Defaults to None. Either ``url`` or the ``domain`` / ``path`` pair must be set, but not both. | - | ``domain`` | Given domain for the cookie. Defaults to None. Either ``url`` or the ``domain`` / ``path`` pair must be set, but not both. | - | ``path`` | Given path for the cookie. Defaults to None. Either ``url`` or the ``domain`` / ``path`` pair must be set, but not both. | - | ``expires`` | Given expiry for the cookie. Can be a date, a unix time or a datetime object. Supports the same formats as the [http://robotframework.org/robotframework/latest/libraries/DateTime.html|DateTime] library or an epoch timestamp. Example: 2027-09-28 16:21:35 | - | ``httpOnly`` | Sets the httpOnly token. | - | ``secure`` | Sets the secure token. | - | ``sameSite`` | Sets the sameSite mode. Can be ``Strict``, ``Lax`` or ``None``. | + *Arguments:* + - ``name``: Name of the cookie. + - ``value``: Given value for the cookie. + - ``url``: Given url for the cookie. Defaults to None. Either ``url`` or the + ``domain`` / ``path`` pair must be set, but not both. + - ``domain``: Given domain for the cookie. Defaults to None. Either ``url`` or + the ``domain`` / ``path`` pair must be set, but not both. + - ``path``: Given path for the cookie. Defaults to None. Either ``url`` or the + ``domain`` / ``path`` pair must be set, but not both. + - ``expires``: Given expiry for the cookie. Can be a date, a unix time or a + datetime object. Supports the same formats as the + [http://robotframework.org/robotframework/latest/libraries/DateTime.html | DateTime] + library or an epoch timestamp. Example: ``2027-09-28 16:21:35`` + - ``httpOnly``: Sets the httpOnly token. + - ``secure``: Sets the secure token. + - ``sameSite``: Sets the sameSite mode. Can be ``Strict``, ``Lax`` or + ``None``. Example: | `Add Cookie` foo bar http://address.com/path/to/site # Using url argument. @@ -182,9 +188,10 @@ def get_cookie( ) -> DotDict | str: """Returns information about the cookie named ``cookie`` as a Robot Framework dot dictionary or a string. - | =Arguments= | =Description= | - | ``cookie`` | Name of the cookie to be retrieved. | - | ``return_type`` | Type of the return value. Can be either ``dictionary`` or ``string``. Defaults to ``dictionary``. | + *Arguments:* + - ``cookie``: Name of the cookie to be retrieved. + - ``return_type``: Type of the return value. Can be either ``dictionary`` or + ``string``. Defaults to ``dictionary``. If ``return_type`` is ``dictionary`` or ``dict``, then the keyword returns a Robot Framework [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#accessing-list-and-dictionary-items|dot dictionary]. diff --git a/Browser/keywords/coverage.py b/Browser/keywords/coverage.py index ae6503b17..8bb5f9f6a 100644 --- a/Browser/keywords/coverage.py +++ b/Browser/keywords/coverage.py @@ -37,13 +37,19 @@ def start_coverage( ) -> str: """Starts the coverage for the current page. - | =Arguments= | =Description= | - | ``config_file`` | Optional path to [https://www.npmjs.com/package/monocart-coverage-reports#options|options file]. If the file does not exist, it is ignored. | - | ``coverage_type`` | Type of coverage to start. Default is ``all``. | - | ``path`` | Absolute or relative directory path (relative to ``${OUTPUT_DIR}/browser/coverage/``) where the coverage is stored in a directory with the page id name. | - | ``raw`` | Whether to save raw coverage data. Default is ``False``. | - | ``reportAnonymousScripts`` | Whether to report anonymous scripts. Default is ``False``. Only valid for JS coverage. | - | ``resetOnNavigation`` | Whether to reset coverage on navigation. Default is ``True``. | + *Arguments:* + - ``config_file``: Optional path to + [https://www.npmjs.com/package/monocart-coverage-reports#options | + options file]. If the file does not exist, it is ignored. + - ``coverage_type``: Type of coverage to start. Default is ``all``. + - ``path``: Absolute or relative directory path (relative to + ``${OUTPUT_DIR}/browser/coverage/``) where the coverage is stored in a + directory with the page id name. + - ``raw``: Whether to save raw coverage data. Default is ``False``. + - ``reportAnonymousScripts``: Whether to report anonymous scripts. Default is + ``False``. Only valid for JS coverage. + - ``resetOnNavigation``: Whether to reset coverage on navigation. Default is + ``True``. The ``coverage_type`` can be one of the following: - ``all``: Both [https://playwright.dev/docs/api/class-coverage/#coverage-start-css-coverage|CSS] and [https://playwright.dev/docs/api/class-coverage/#coverage-start-js-coverage|JS]. @@ -135,12 +141,15 @@ def merge_coverage_reports( ) -> Path: """Combines multiple raw coverage reports into a single report. - | =Arguments= | =Description= | - | ``input_folder`` | Path to the base folder where the raw coverage reports are located. | - | ``output_folder`` | Path to the folder where the combined report is stored. | - | ``config_file`` | Optional path to [https://www.npmjs.com/package/monocart-coverage-reports#options|options file] | - | ``name`` | Optional name for the combined report. | - | ``reports`` | Optional list of reporters to create. Default is ``v8``. | + *Arguments:* + - ``input_folder``: Path to the base folder where the raw coverage reports are + located. + - ``output_folder``: Path to the folder where the combined report is stored. + - ``config_file``: Optional path to + [https://www.npmjs.com/package/monocart-coverage-reports#options | + options file] + - ``name``: Optional name for the combined report. + - ``reports``: Optional list of reporters to create. Default is ``v8``. Returns the path to the ``output_folder``. diff --git a/Browser/keywords/crawling.py b/Browser/keywords/crawling.py index 4041f37b2..603641f49 100644 --- a/Browser/keywords/crawling.py +++ b/Browser/keywords/crawling.py @@ -25,11 +25,18 @@ def crawl_site( Returns the list of crawled urls. The order of the returned urls is not guaranteed to be the order in which the pages were crawled. - | =Arguments= | =Description= | - | ``url`` | is the page to start crawling from. If it is given, a `New Page` is opened with that url. If it is not given, crawling starts from the url of the current page. | - | ``page_crawl_keyword`` | is the keyword that will be executed on every page. It is run without arguments. By default it will take a screenshot on every page. | - | ``max_number_of_page_to_crawl`` | is the upper limit of pages to crawl. Crawling will stop when this number of pages has been crawled. | - | ``max_depth_to_crawl`` | is the upper limit of consecutive links followed from the start page. The start page has depth ``0`` and links deeper than this limit are not followed. | + *Arguments:* + - ``url``: is the page to start crawling from. If it is given, a `New Page` is + opened with that url. If it is not given, crawling starts from the url + of the current page. + - ``page_crawl_keyword``: is the keyword that will be executed on every page. + It is run without arguments. By default it will take a screenshot on + every page. + - ``max_number_of_page_to_crawl``: is the upper limit of pages to crawl. + Crawling will stop when this number of pages has been crawled. + - ``max_depth_to_crawl``: is the upper limit of consecutive links followed + from the start page. The start page has depth ``0`` and links deeper + than this limit are not followed. [https://forum.robotframework.org/t//4243|Comment >>] """ diff --git a/Browser/keywords/credential.py b/Browser/keywords/credential.py index d722e3bb1..6ad137230 100644 --- a/Browser/keywords/credential.py +++ b/Browser/keywords/credential.py @@ -38,12 +38,14 @@ def create_credential( pages that are created from that context. There must be an open context, otherwise the keyword fails. - | =Arguments= | =Description= | - | rpId | Relying party id (typically the site's effective domain). | - | id_ | Base64url-encoded credential id. Auto-generated if omitted. | - | privateKey | Base64url-encoded PKCS#8 (DER) private key. Auto-generated if omitted. | - | publicKey | Base64url-encoded SPKI (DER) public key. Auto-generated if omitted. | - | userHandle | Base64url-encoded user handle. Auto-generated if omitted. | + *Arguments:* + - ``rpId``: Relying party id (typically the site's effective domain). + - ``id_``: Base64url-encoded credential id. Auto-generated if omitted. + - ``privateKey``: Base64url-encoded PKCS#8 (DER) private key. Auto-generated + if omitted. + - ``publicKey``: Base64url-encoded SPKI (DER) public key. Auto-generated if + omitted. + - ``userHandle``: Base64url-encoded user handle. Auto-generated if omitted. Because ``privateKey`` and ``publicKey`` are sensitive information, it is recommended to wrap their values in the Secret type. The Secret type requires Robot Framework 7.4 @@ -146,9 +148,9 @@ def get_credential( credential matches, the first match is returned. When no credential matches, the keyword fails. - | =Arguments= | =Description= | - | id_ | Base64url-encoded credential id. | - | rpId | Relying party id (typically the site's effective domain). | + *Arguments:* + - ``id_``: Base64url-encoded credential id. + - ``rpId``: Relying party id (typically the site's effective domain). The returned credential is a dictionary with the following keys: | =Key= | =Description= | @@ -200,8 +202,8 @@ def get_credential( def delete_credential(self, id_: str): """Deletes the credential with the given id. - | =Arguments= | =Description= | - | id_ | Base64url-encoded credential id. | + *Arguments:* + - ``id_``: Base64url-encoded credential id. Deleting a credential which does not exist does not fail. There must be an open context, otherwise the keyword fails. diff --git a/Browser/keywords/device_descriptors.py b/Browser/keywords/device_descriptors.py index effb92ef3..26c3688ff 100644 --- a/Browser/keywords/device_descriptors.py +++ b/Browser/keywords/device_descriptors.py @@ -42,8 +42,9 @@ def get_devices(self) -> dict: def get_device(self, name: str) -> dict: """Returns a single device descriptor whose name matches ``name`` exactly. - | =Arguments= | =Description= | - | ``name`` | Name of the requested device. See Playwright's [https://github.com/microsoft/playwright/blob/master/packages/playwright-core/src/server/deviceDescriptorsSource.json|deviceDescriptorsSource.json] for a formatted list. | + *Arguments:* + - ``name``: Name of the requested device. See Playwright's + [https://github.com/microsoft/playwright/blob/master/packages/playwright-core/src/server/deviceDescriptorsSource.json|deviceDescriptorsSource.json] for a formatted list. The keyword fails if there is no device with that name. The matching is case sensitive. diff --git a/Browser/keywords/evaluation.py b/Browser/keywords/evaluation.py index 2d5e7f311..c4093c28e 100644 --- a/Browser/keywords/evaluation.py +++ b/Browser/keywords/evaluation.py @@ -45,11 +45,22 @@ def evaluate_javascript( available, but Robot Framework variables and Python objects are not. Only ``arg`` and the resolved element(s) are passed into the page. - | =Arguments= | =Description= | - | ``selector`` | Selector to resolve and pass to the JavaScript function. This will be the first argument the function receives if not ``${None}``. ``selector`` is optional and can be omitted. If given a selector, a function is necessary, with an argument to capture the element. For example ``(element) => document.activeElement === element`` See the `Finding elements` section for details about the selectors. | - | ``*function`` | A valid javascript function or a javascript function body. These arguments can be used to write readable multiline JavaScript. | - | ``arg`` | an additional argument that can be handed over to the JavaScript function. It is the second argument of the function when a ``selector`` is given, otherwise the first one. This argument must be JSON serializable. ElementHandles are not supported. | - | ``all_elements`` | defines if only the single element found by ``selector`` is handed over to the function or if set to ``True`` all found elements are handed over as array. | + *Arguments:* + - ``selector``: Selector to resolve and pass to the JavaScript function. This + will be the first argument the function receives if not ``${None}``. + ``selector`` is optional and can be omitted. If given a selector, a + function is necessary, with an argument to capture the element. + + For example ``(element) => document.activeElement === element`` + - ``*function``: A valid javascript function or a javascript function body. + These arguments can be used to write readable multiline JavaScript. + - ``arg``: an additional argument that can be handed over to the JavaScript + function. It is the second argument of the function when a ``selector`` + is given, otherwise the first one. This argument must be JSON + serializable. ElementHandles are not supported. + - ``all_elements``: defines if only the single element found by ``selector`` + is handed over to the function or if set to ``True`` all found elements + are handed over as array. The value returned by the JavaScript is transferred as JSON and must therefore be JSON serializable. DOM nodes and other non serializable objects can not be returned. @@ -110,13 +121,21 @@ def highlight_elements( elements in the page. Keyword does not scroll elements to viewport and highlighted element might be outside the viewport. Use `Scroll To Element` keyword to scroll element in viewport. - | =Arguments= | =Description= | - | ``selector`` | Selectors which shall be highlighted. See the `Finding elements` section for details about the selectors. | - | ``duration`` | Sets for how long the selector shall be highlighted. Defaults to ``5s`` => 5 seconds. If set to 0 seconds, the highlighting is not deleted. | - | ``width`` | Sets the width of the highlight border. Defaults to 2px. | - | ``style`` | Sets the style of the border. Defaults to dotted. | - | ``color`` | Sets the color of the border. Valid colors i.e. are: ``red``, ``blue``, ``yellow``, ``pink``, ``black`` | - | ``mode`` | Sets the mode of the highlight. Valid modes are: ``border`` (classic mode), ``playwright`` (Playwright's native one) and ``both``. Defaults to ``border``. If ``playwright`` is used, ``width``, ``style`` and ``color`` are ignored and only one highlighting can happen at the same time. | + *Arguments:* + - ``selector``: Selectors which shall be highlighted. See the `Finding + elements` section for details about the selectors. + - ``duration``: Sets for how long the selector shall be highlighted. Defaults + to ``5s`` => 5 seconds. If set to 0 seconds, the highlighting is not + deleted. + - ``width``: Sets the width of the highlight border. Defaults to 2px. + - ``style``: Sets the style of the border. Defaults to dotted. + - ``color``: Sets the color of the border. Valid colors i.e. are: ``red``, + ``blue``, ``yellow``, ``pink``, ``black`` + - ``mode``: Sets the mode of the highlight. Valid modes are: ``border`` + (classic mode), ``playwright`` (Playwright's native one) and ``both``. + Defaults to ``border``. If ``playwright`` is used, ``width``, ``style`` + and ``color`` are ignored and only one highlighting can happen at the + same time. Keyword does not fail if selector resolves to multiple elements. @@ -161,8 +180,8 @@ def add_style_tag(self, content: str): The tag is added to the currently active page and it is lost when the page is navigated to a new url. - | =Arguments= | =Description= | - | ``content`` | Raw CSS content to be injected into the current page. | + *Arguments:* + - ``content``: Raw CSS content to be injected into the current page. Example: | `Add Style Tag` \\#username_field:focus {background-color: aqua;} @@ -183,11 +202,19 @@ def download( ) -> DownloadInfo: """Download given url content. - | =Arguments= | =Description= | - | ``url`` | URL to the file that shall be downloaded. | - | ``saveAs`` | Path where the file shall be saved persistently. If empty, generated unique path (GUID) is used and file is deleted when the context is closed. | - | ``wait_for_finished`` | If set to ``False`` keyword returns immediately after the download has started. Defaults to ``True``. | - | ``download_timeout`` | Maximum total time for the file to be fetched and saved. If the file is not fetched within this time, the keyword fails. If it is fetched but not saved, the download is cancelled and the keyword fails. If ``wait_for_finished`` is ``False``, only the fetching is limited. If not set, the file must be fetched within the browser timeout, see `Set Browser Timeout`, and there is no limit for saving it. | + *Arguments:* + - ``url``: URL to the file that shall be downloaded. + - ``saveAs``: Path where the file shall be saved persistently. If empty, + generated unique path (GUID) is used and file is deleted when the + context is closed. + - ``wait_for_finished``: If set to ``False`` keyword returns immediately after + the download has started. Defaults to ``True``. + - ``download_timeout``: Maximum total time for the file to be fetched and + saved. If the file is not fetched within this time, the keyword fails. + If it is fetched but not saved, the download is cancelled and the + keyword fails. If ``wait_for_finished`` is ``False``, only the fetching + is limited. If not set, the file must be fetched within the browser + timeout, see `Set Browser Timeout`, and there is no limit for saving it. Keyword returns dictionary of type `DownloadInfo`. diff --git a/Browser/keywords/getters.py b/Browser/keywords/getters.py index a0f62e947..790352ebb 100644 --- a/Browser/keywords/getters.py +++ b/Browser/keywords/getters.py @@ -78,15 +78,25 @@ def get_aria_snapshot( ) -> str | dict | list | tuple: """Returns the aria snapshot of the element found by ``selector``. See `AriaSnapshotReturnType` for more details and examples. - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``return_type`` | Defines the return type. Possible values are ``yaml`` (default), ``dict`` and ``parsed``. If ``yaml`` is selected, the returned value is a string in YAML format. If ``dict`` is selected, the returned value is a dictionary. If ``parsed`` is selected, the returned value is a tree of node dictionaries. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | - | ``mode`` | Defines the snapshot mode. Possible values are ``default`` (default) and ``ai``. See `AriaSnapshotMode` for more details. | - | ``depth`` | Limits the snapshot to the given number of tree levels. Must be a positive integer. Defaults to ``None``, which does not limit the depth. | - | ``boxes`` | If ``True``, the bounding box of each element is appended to its line as ``[box=x,y,width,height]``. Coordinates are relative to the viewport, in CSS pixels. Defaults to ``False``. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``return_type``: Defines the return type. Possible values are ``yaml`` + (default), ``dict`` and ``parsed``. If ``yaml`` is selected, the + returned value is a string in YAML format. If ``dict`` is selected, the + returned value is a dictionary. If ``parsed`` is selected, the returned + value is a tree of node dictionaries. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. + - ``mode``: Defines the snapshot mode. Possible values are ``default`` + (default) and ``ai``. See `AriaSnapshotMode` for more details. + - ``depth``: Limits the snapshot to the given number of tree levels. Must be a + positive integer. Defaults to ``None``, which does not limit the depth. + - ``boxes``: If ``True``, the bounding box of each element is appended to its + line as ``[box=x,y,width,height]``. Coordinates are relative to the + viewport, in CSS pixels. Defaults to ``False``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -153,10 +163,11 @@ def get_url( ) -> str | dict | tuple: """Returns the current URL. - | =Arguments= | =Description= | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Optionally asserts that it matches the specified assertion. See `Assertions` for further details for the assertion arguments. By default assertion is not done. @@ -183,10 +194,11 @@ def get_page_source( ) -> str | dict | tuple: """Gets the page's HTML source as a string. - | =Arguments= | =Description= | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Optionally does a string assertion. See `Assertions` for further details for the assertion arguments. By default assertion is not done. @@ -225,10 +237,11 @@ def get_title( ) -> str | dict | tuple: """Returns the title of the current page. - | =Arguments= | =Description= | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Optionally asserts that title matches the specified assertion. See `Assertions` for further details for the assertion arguments. By default assertion is not done. @@ -267,12 +280,17 @@ def get_text( Keyword can also return the value property text of ``input`` or ``textarea`` elements. See the `Finding elements` section for details about the selectors. - | =Arguments= | =Description= | - | ``selector`` | Selector from which the text is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | - | ``text_type`` | How text is returned. Possible values are ``allInnerTexts``, ``allTextContents``, ``innerText``, ``inputValue``, and ``innerHTML``. Defaults to ``None``, which returns the value of ``input`` and ``textarea`` elements and the inner text of all other elements. | + *Arguments:* + - ``selector``: Selector from which the text is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. + - ``text_type``: How text is returned. Possible values are ``allInnerTexts``, + ``allTextContents``, ``innerText``, ``inputValue``, and ``innerHTML``. + Defaults to ``None``, which returns the value of ``input`` and + ``textarea`` elements and the inner text of all other elements. Keyword uses strict mode, see `Finding elements` for more details about strict mode. The ``text_type`` argument determines how text is returned. The ``allInnerTexts`` and @@ -336,12 +354,14 @@ def get_property( ) -> Any: """Returns the ``property`` of the element found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``property`` | Requested property name. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``property``: Requested property name. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -396,12 +416,14 @@ def get_attribute( ) -> str | tuple | dict | None: """Returns the HTML ``attribute`` of the element found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``attribute`` | Requested attribute name. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``attribute``: Requested attribute name. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -458,12 +480,13 @@ def get_attribute_names( ) -> list[str]: """Returns all HTML attribute names of an element as a list. - - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``*assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``*assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -511,12 +534,13 @@ def get_classes( ) -> list[str]: """Returns all classes of an element as a list. - - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``*assertion_expected`` | Expected values for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``*assertion_expected``: Expected values for the state + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -561,12 +585,13 @@ def get_select_options( Each returned dictionary has the keys "index", "value", "label" and "selected". - - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -618,12 +643,15 @@ def get_selected_options( ) -> list[str | int]: """Returns the specified attribute of selected options of the ``select`` element. - | =Arguments= | =Description= | - | ``selector`` | Selector from which the info is to be retrieved. See the `Finding elements` section for details about the selectors. | - | ``option_attribute`` | Which attribute shall be returned/verified. Defaults to label. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``*assertion_expected`` | Expected value for the state | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector from which the info is to be retrieved. See the + `Finding elements` section for details about the selectors. + - ``option_attribute``: Which attribute shall be returned/verified. Defaults + to label. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``*assertion_expected``: Expected value for the state + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -684,14 +712,19 @@ def get_checkbox_state( `Assertions` for further details for the assertion arguments. By default assertion is not done. - | =Arguments= | =Description= | - | ``selector`` | Selector which shall be examined. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | ``==`` and ``!=`` and equivalent are allowed on boolean values. Other operators are not accepted. | - | ``assertion_expected`` | Boolean value of expected state. Strings are interpreted as booleans. All strings are ``${True}`` except the following: ``FALSE, NO, OFF, 0, UNCHECKED, NONE, ${EMPTY}`` (case-insensitive). Defaults to ``Unchecked``. | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector which shall be examined. See the `Finding elements` + section for details about the selectors. + - ``assertion_operator``: ``==`` and ``!=`` and equivalent are allowed on + boolean values. Other operators are not accepted. + - ``assertion_expected``: Boolean value of expected state. Strings are + interpreted as booleans. All strings are ``${True}`` except the + following: ``FALSE``, ``NO``, ``OFF``, ``0``, ``UNCHECKED``, ``NONE``, ``${EMPTY}`` + (case-insensitive). Defaults to ``UNCHECKED``. + - ``message``: overrides the default error message for assertion. - - ``checked`` => ``True`` - - ``unchecked`` => ``False`` + - ``CHECKED`` => ``True`` + - ``UNCHECKED`` => ``False`` Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -729,11 +762,13 @@ def get_element_count( ) -> int: """Returns the count of elements found with ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector which shall be counted. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Selector which shall be counted. See the `Finding elements` + section for details about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Optionally asserts that the count matches the specified assertion. See `Assertions` for further details for the assertion arguments. By default assertion @@ -769,11 +804,16 @@ def get_viewport_size( ) -> ViewportDimensions | None: """Returns the current viewport dimensions. - | =Arguments= | =Description= | - | ``key`` | Optionally filters the returned values. If keys is set to ``ALL`` (default) it will return the viewport size as dictionary, otherwise it will just return the single value selected by the key. Note: If a single value is retrieved, an assertion does *not* need a ``validate`` combined with a cast of ``value``. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``key``: Optionally filters the returned values. If keys is set to ``ALL`` + (default) it will return the viewport size as dictionary, otherwise it + will just return the single value selected by the key. Note: If a single + value is retrieved, an assertion does *not* need a ``validate`` combined + with a cast of ``value``. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Optionally asserts that the state matches the specified assertion. See `Assertions` for further details for the assertion arguments. By default assertion @@ -819,10 +859,13 @@ def get_table_cell_element(self, table: str, column: str, row: str) -> str: The returned value is used like the one from `Get Element`. - | =Arguments= | =Description= | - | ``table`` | selector must select the ```` element that contains both selected elements | - | ``column`` | selector can select any ```` element or one of their descendants like ``
`` or ```` element or one of their descendants. | - | ``row`` | selector can select any ``
`` elements. | + *Arguments:* + - ``table``: selector must select the ```` element that contains both + selected elements + - ``column``: selector can select any ```` element or one of their + descendants like ````, ````, ``
`` or ```` element or one of + their descendants. + - ``row``: selector can select any ``
`` elements. ``column`` and ``row`` can also consume index numbers instead of selectors. Indexes are starting from ``0`` and ``-1`` is specific for the last element. @@ -881,11 +924,14 @@ def get_table_cell_index( ) -> int: """Returns the index (0 based) of a table cell within its row. - | =Arguments= | =Description= | - | ``selector`` | can select any ```` or ```` element or one of their descendants. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: can select any ```` or ```` element or one of their + descendants. See the `Finding elements` section for details about the + selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Example: | ${table}= Set Variable id=`Get Table Cell Element` >> div.kw-docs table #Table of keyword `Get Table Cell Element` @@ -924,12 +970,14 @@ def get_table_row_index( ) -> int: """Returns the index (0 based) of a table row. - - | =Arguments= | =Description= | - | ``selector`` | can select any ``
`` or ```` element or one of their descendants. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: can select any ``
`` or ```` element or one + of their descendants. See the `Finding elements` section for details + about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Example: | ${table}= Set Variable id=`Get Table Cell Element` >> div.kw-docs table #Table of keyword `Get Table Cell Element` @@ -966,9 +1014,9 @@ def get_element(self, selector: str) -> str: selector, chained with ``>>``. Because it is a selector and not a captured DOM node, it is resolved again from the page on every use. - - | =Arguments= | =Description= | - | ``selector`` | Selector from which the element shall be retrieved. See the `Finding elements` section for details about the selectors. | + *Arguments:* + - ``selector``: Selector from which the element shall be retrieved. See the + `Finding elements` section for details about the selectors. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -994,9 +1042,9 @@ def get_elements(self, selector: str) -> list[str]: Each string can be used as the *first* clause of another selector, chained with ``>>``, exactly like the value returned by `Get Element`. - - | =Arguments= | =Description= | - | ``selector`` | Selector from which the elements shall be retrieved. See the `Finding elements` section for details about the selectors. | + *Arguments:* + - ``selector``: Selector from which the elements shall be retrieved. See the + `Finding elements` section for details about the selectors. Keyword does not use strict mode and returns an empty list if the ``selector`` does not match any element. @@ -1067,18 +1115,26 @@ def get_element_by_role( | ${checkbox} Get Element By Role checkbox name=Subscribe | ${button} Get Element By Role button name=/submit/i - | =Arguments= | =Description= | - | ``all_elements`` | If True, returns all matched elements as a list. | - | ``role`` | Role from which shall be retrieved. | - | ``checked`` | An attribute that is usually set by aria-checked or native controls. | - | ``disabled`` | An attribute that is usually set by aria-disabled or disabled. | - | ``exact`` | Whether name is matched exactly: case-sensitive and whole-string. Defaults to false. Ignored when name is a regular expression. Note that exact match still trims whitespace. | - | ``expanded`` | An attribute that is usually set by aria-expanded. | - | ``include_hidden`` | Option that controls whether hidden elements are matched. By default, only non-hidden elements, as defined by ARIA, are matched by role selector. | - | ``level`` | A number attribute that is usually present for roles heading, list item, row, treeitem, with default values for

-

elements. | - | ``name`` | Option to match the accessible name. By default, matching is case-insensitive and searches for a substring, use exact to control this behavior. | - | ``pressed`` | An attribute that is usually set by aria-pressed. | - | ``selected`` | An attribute that is usually set by aria-selected. | + *Arguments:* + - ``all_elements``: If True, returns all matched elements as a list. + - ``role``: Role from which shall be retrieved. + - ``checked``: An attribute that is usually set by aria-checked or native + controls. + - ``disabled``: An attribute that is usually set by aria-disabled or disabled. + - ``exact``: Whether name is matched exactly: case-sensitive and whole-string. + Defaults to false. Ignored when name is a regular expression. Note that + exact match still trims whitespace. + - ``expanded``: An attribute that is usually set by aria-expanded. + - ``include_hidden``: Option that controls whether hidden elements are + matched. By default, only non-hidden elements, as defined by ARIA, are + matched by role selector. + - ``level``: A number attribute that is usually present for roles heading, + list item, row, treeitem, with default values for

-

elements. + - ``name``: Option to match the accessible name. By default, matching is + case-insensitive and searches for a substring, use exact to control this + behavior. + - ``pressed``: An attribute that is usually set by aria-pressed. + - ``selected``: An attribute that is usually set by aria-selected. If an element shall be fetched from an iframe, a selector prefix must be set using `Set Selector Prefix` keyword including ``>>>`` as ending. @@ -1137,11 +1193,15 @@ def get_element_by( Selection strategies can be several Playwright strategies like AltText or Label. See [https://playwright.dev/docs/locators|Playwright Locators] for more information. - | =Arguments= | =Description= | - | ``selection_strategy`` | SelectionStrategy to be used. Refers to Playwrights ``page.getBy***`` functions. See https://playwright.dev/docs/locators | - | ``text`` | Text to locate the element for. | - | ``exact`` | Whether to find an exact match: case-sensitive and whole-string. Defaults to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace. This has no effect if RegExp is used or if TestID is used as strategy. | - | ``all_elements`` | If True, returns all matched elements as a list. | + *Arguments:* + - ``selection_strategy``: SelectionStrategy to be used. Refers to Playwrights + ``page.getBy***`` functions. See https://playwright.dev/docs/locators + - ``text``: Text to locate the element for. + - ``exact``: Whether to find an exact match: case-sensitive and whole-string. + Defaults to false. Ignored when locating by a regular expression. Note + that exact match still trims whitespace. This has no effect if RegExp is + used or if TestID is used as strategy. + - ``all_elements``: If True, returns all matched elements as a list. This keywords implements the following Playwright functions: - [https://playwright.dev/docs/api/class-page#page-get-by-alt-text|page.getByAltText] @@ -1198,14 +1258,17 @@ def get_style( # ruff: ignore[PLR0917] ) -> dict[str, str] | str | tuple | dict: """Gets the computed style properties of the element selected by ``selector``. - - | =Arguments= | =Description= | - | ``selector`` | Selector from which the style shall be retrieved. See the `Finding elements` section for details about the selectors. | - | ``key`` | Key of the requested CSS property. Retrieves "ALL" styles as dictionary by default. All css settings can be used as keys even if they are not all returned in the dictionary. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | - | ``pseudo_element`` | Pseudo element to match. Defaults to None. | + *Arguments:* + - ``selector``: Selector from which the style shall be retrieved. See the + `Finding elements` section for details about the selectors. + - ``key``: Key of the requested CSS property. Retrieves "ALL" styles as + dictionary by default. All css settings can be used as keys even if they + are not all returned in the dictionary. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. + - ``pseudo_element``: Pseudo element to match. Defaults to None. A [https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements|pseudo element] is a CSS functionality to add styles, for example ``::before`` or ``::after``. @@ -1279,13 +1342,21 @@ def get_boundingbox( To allow also hidden elements without a bounding box, set ``allow_hidden`` to ``True``, which results in a return value of ``None`` in case of no bounding box. - | =Arguments= | =Description= | - | ``selector`` | Selector from which the bounding box shall be retrieved. See the `Finding elements` section for details about the selectors. | - | ``key`` | Optionally filters the returned values. If keys is set to ``ALL`` (default) it will return the BoundingBox as Dictionary, otherwise it will just return the single value selected by the key. Note: If a single value is retrieved, an assertion does *not* need a ``validate`` combined with a cast of ``value``. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | - | ``allow_hidden`` | (named only) If True, hidden elements are not causing a failure and will return ``None``. Otherwise a hidden element will fail. Defaults to False. | + *Arguments:* + - ``selector``: Selector from which the bounding box shall be retrieved. See + the `Finding elements` section for details about the selectors. + - ``key``: Optionally filters the returned values. If keys is set to ``ALL`` + (default) it will return the BoundingBox as Dictionary, otherwise it + will just return the single value selected by the key. Note: If a single + value is retrieved, an assertion does *not* need a ``validate`` combined + with a cast of ``value``. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. + - ``allow_hidden``: (named only) If True, hidden elements are not causing a + failure and will return ``None``. Otherwise a hidden element will fail. + Defaults to False. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -1353,13 +1424,18 @@ def get_scroll_size( ) -> Dimensions | float | int: """Gets elements or pages scrollable size as object ``{width: float, height: float}``. - - | =Arguments= | =Description= | - | ``selector`` | Optional selector from which the scroll size shall be retrieved. If no selector is given the scroll size of the page itself is used. See the `Finding elements` section for details about the selectors. | - | ``key`` | Optionally filters the returned values. If keys is set to ``ALL`` (default) it will return the scroll size as dictionary, otherwise it will just return the single value selected by the key. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Optional selector from which the scroll size shall be + retrieved. If no selector is given the scroll size of the page itself is + used. See the `Finding elements` section for details about the + selectors. + - ``key``: Optionally filters the returned values. If keys is set to ``ALL`` + (default) it will return the scroll size as dictionary, otherwise it + will just return the single value selected by the key. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -1412,13 +1488,18 @@ def get_scroll_position( It describes the rectangle which is visible of the scrollable content of that element. All values are measured from position {top: 0, left: 0}. - - | =Arguments= | =Description= | - | ``selector`` | Optional selector from which the scroll position shall be retrieved. If no selector is given the scroll position of the page itself is used (``document.scrollingElement``). See the `Finding elements` section for details about the selectors. | - | ``key`` | Optionally filters the returned values. If keys is set to ``ALL`` (default) it will return the scroll position as dictionary, otherwise it will just return the single value selected by the key. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Optional selector from which the scroll position shall be + retrieved. If no selector is given the scroll position of the page + itself is used (``document.scrollingElement``). See the `Finding + elements` section for details about the selectors. + - ``key``: Optionally filters the returned values. If keys is set to ``ALL`` + (default) it will return the scroll position as dictionary, otherwise it + will just return the single value selected by the key. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -1465,13 +1546,18 @@ def get_client_size( ) -> Dimensions | float: """Gets elements or pages client size (``clientHeight``, ``clientWidth``) as object {width: float, height: float}. - - | =Arguments= | =Description= | - | ``selector`` | Optional selector from which the client size shall be retrieved. If no selector is given the client size of the page itself is used (``document.scrollingElement``). See the `Finding elements` section for details about the selectors. | - | ``key`` | Optionally filters the returned values. If keys is set to ``ALL`` (default) it will return the client size as dictionary, otherwise it will just return the single value selected by the key. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected value for the assertion | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``selector``: Optional selector from which the client size shall be + retrieved. If no selector is given the client size of the page itself is + used (``document.scrollingElement``). See the `Finding elements` section + for details about the selectors. + - ``key``: Optionally filters the returned values. If keys is set to ``ALL`` + (default) it will return the client size as dictionary, otherwise it + will just return the single value selected by the key. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected value for the assertion + - ``message``: overrides the default error message for assertion. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -1517,13 +1603,16 @@ def get_element_states( This Keyword returns a list of states that are valid for the selected element. - - | =Arguments= | =Description= | - | ``selector`` | Selector of the corresponding object. See the `Finding elements` section for details about the selectors. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``*assertion_expected`` | Expected states | - | ``message`` | overrides the default error message for assertion. | - | ``return_names`` | If set to ``False`` the keyword does return an IntFlag object (`ElementState`) instead of a list. `ElementState` may contain multiple states at the same time. Defaults to ``True``. | + *Arguments:* + - ``selector``: Selector of the corresponding object. See the `Finding + elements` section for details about the selectors. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``*assertion_expected``: Expected states + - ``message``: overrides the default error message for assertion. + - ``return_names``: If set to ``False`` the keyword does return an IntFlag + object (`ElementState`) instead of a list. `ElementState` may contain + multiple states at the same time. Defaults to ``True``. Optionally asserts that the state matches the specified assertion. See `Assertions` for further details for the assertion arguments. By default, assertion @@ -1605,11 +1694,14 @@ def get_download_state( | downloadID: Optional[str] | } - | =Arguments= | =Description= | - | ``download`` | `DownloadInfo` dictionary returned from `Promise To Wait For Download` or download id as string. | - | ``assertion_operator`` | See `Assertions` for further details. Defaults to None. | - | ``assertion_expected`` | Expected state of the download. Be aware that the returned value is a dictionary | - | ``message`` | overrides the default error message for assertion. | + *Arguments:* + - ``download``: `DownloadInfo` dictionary returned from `Promise To Wait For + Download` or download id as string. + - ``assertion_operator``: See `Assertions` for further details. Defaults to + None. + - ``assertion_expected``: Expected state of the download. Be aware that the + returned value is a dictionary + - ``message``: overrides the default error message for assertion. [https://forum.robotframework.org/t//6479|Comment >>] """ diff --git a/Browser/keywords/interaction.py b/Browser/keywords/interaction.py index 0afc7a70c..64bb3894a 100644 --- a/Browser/keywords/interaction.py +++ b/Browser/keywords/interaction.py @@ -60,11 +60,16 @@ def type_text( Sends a ``keydown``, ``keypress/input``, and ``keyup`` event for each character in the text. - | =Arguments= | =Description= | - | ``selector`` | Selector of the text field. See the `Finding elements` section for details about the selectors. | - | ``txt`` | Text for the text field. | - | ``delay`` | Delay between the single key strokes. It may be either a number or a Robot Framework time string. Time strings are fully explained in an appendix of Robot Framework User Guide. Defaults to ``0 ms``. Example: ``50 ms`` | - | ``clear`` | Set to ``False`` if the field should not be cleared before typing. Defaults to ``True``. | + *Arguments:* + - ``selector``: Selector of the text field. See the `Finding elements` section + for details about the selectors. + - ``txt``: Text for the text field. + - ``delay``: Delay between the single key strokes. It may be either a number + or a Robot Framework time string. Time strings are fully explained in an + appendix of Robot Framework User Guide. Defaults to ``0 ms``. Example: + ``50 ms`` + - ``clear``: Set to ``False`` if the field should not be cleared before + typing. Defaults to ``True``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -97,11 +102,12 @@ def fill_text(self, selector: str, txt: str, force: bool = False): [contenteditable] element, this keyword fails. Note that you can pass an empty string as ``txt`` to clear the input field. - - | =Arguments= | =Description= | - | ``selector`` | Selector of the text field. See the `Finding elements` section for details about the selectors. | - | ``txt`` | Text for the text field. | - | ``force`` | Set to ``True`` to skip Playwright's [https://playwright.dev/docs/actionability|Actionability checks]. | + *Arguments:* + - ``selector``: Selector of the text field. See the `Finding elements` section + for details about the selectors. + - ``txt``: Text for the text field. + - ``force``: Set to ``True`` to skip Playwright's + [https://playwright.dev/docs/actionability | Actionability checks]. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -119,8 +125,9 @@ def fill_text(self, selector: str, txt: str, force: bool = False): def clear_text(self, selector: str): """Clears the text field found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the text field. See the `Finding elements` section for details about the selectors. | + *Arguments:* + - ``selector``: Selector of the text field. See the `Finding elements` section + for details about the selectors. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -143,11 +150,19 @@ def type_secret( ): """Types the given ``secret`` into the text field found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the text field. See the `Finding elements` section for details about the selectors. | - | ``secret`` | Supports Robot Framework 7.4 Secret type as normal variable (with curly braces). Also environment variable name with % prefix or a local variable with $ prefix that has the secret text value (without curly braces). | - | ``delay`` | Delay between the single key strokes. It may be either a number or a Robot Framework time string. Time strings are fully explained in an appendix of Robot Framework User Guide. Defaults to ``0 ms``. Example: ``50 ms`` | - | ``clear`` | Set to ``False`` if the field should not be cleared before typing. Defaults to ``True``. | + *Arguments:* + - ``selector``: Selector of the text field. See the `Finding elements` section + for details about the selectors. + - ``secret``: Supports Robot Framework 7.4 Secret type as normal variable + (with curly braces). Also environment variable name with % prefix or a + local variable with $ prefix that has the secret text value (without + curly braces). + - ``delay``: Delay between the single key strokes. It may be either a number + or a Robot Framework time string. Time strings are fully explained in an + appendix of Robot Framework User Guide. Defaults to ``0 ms``. Example: + ``50 ms`` + - ``clear``: Set to ``False`` if the field should not be cleared before + typing. Defaults to ``True``. This keyword does not log the secret in Robot Framework logs, but if Playwright debug logs are enabled, the secret will be visible as @@ -209,11 +224,16 @@ def type_secret( def fill_secret(self, selector: str, secret: str | Secret, force: bool = False): """Fills the given ``secret`` into the text field found by ``selector``. - - | =Arguments= | =Description= | - | ``selector`` | Selector of the text field. See the `Finding elements` section for details about the selectors. | - | ``secret`` | The secret string that should be filled into the text field. Supports Robot Framework 7.4 Secret type as normal variable (with curly braces). Also environment variable name with % prefix or a local variable with $ prefix that has the secret text value (without curly braces). | - | ``force`` | Set to ``True`` to skip Playwright's [https://playwright.dev/docs/actionability|Actionability checks]. | + *Arguments:* + - ``selector``: Selector of the text field. See the `Finding elements` section + for details about the selectors. + - ``secret``: The secret string that should be filled into the text field. + Supports Robot Framework 7.4 Secret type as normal variable (with curly + braces). Also environment variable name with % prefix or a local + variable with $ prefix that has the secret text value (without curly + braces). + - ``force``: Set to ``True`` to skip Playwright's + [https://playwright.dev/docs/actionability | Actionability checks]. This keyword does not log the secret in Robot Framework logs, but @@ -280,12 +300,17 @@ def press_keys( ): """Types the given key combination into element found by ``selector``. - - | =Arguments= | =Description= | - | ``selector`` | Selector of the text field. See the `Finding elements` section for details about the selectors. | - | ``*keys`` | Keys to be pressed one after the other. Combining modifiers with a single key press by chaining them with ``+``, like ``Control+Shift+T``, is supported. | - | ``press_duration`` | Delay between keydown and keyup of each key. Can be given as seconds (float) or as Robot Framework time string. Defaults to ``0 ms``. Example: ``50 ms`` | - | ``key_delay`` | Delay between key presses. Can be given as seconds (float) or as Robot Framework time string. Defaults to ``0 ms``. Example: ``50 ms`` | + *Arguments:* + - ``selector``: Selector of the text field. See the `Finding elements` section + for details about the selectors. + - ``*keys``: Keys to be pressed one after the other. Combining modifiers with + a single key press by chaining them with ``+``, like + ``Control+Shift+T``, is supported. + - ``press_duration``: Delay between keydown and keyup of each key. Can be + given as seconds (float) or as Robot Framework time string. Defaults to + ``0 ms``. Example: ``50 ms`` + - ``key_delay``: Delay between key presses. Can be given as seconds (float) or + as Robot Framework time string. Defaults to ``0 ms``. Example: ``50 ms`` Supports values like ``a`` or ``b`` which will be automatically typed. @@ -329,10 +354,11 @@ def click(self, selector: str, button: MouseButton = MouseButton.left): - Use `Mouse Button` to click in the center of the element. - Wait for initiated navigation to either succeed or fail. - - | =Arguments= | =Description= | - | ``selector`` | Selector element to click. See the `Finding elements` section for details about the selectors. | - | ``button`` | Mouse button to click with. One of ``left``, ``middle`` or ``right``. Defaults to ``left``. | + *Arguments:* + - ``selector``: Selector element to click. See the `Finding elements` section + for details about the selectors. + - ``button``: Mouse button to click with. One of ``left``, ``middle`` or + ``right``. Defaults to ``left``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -372,17 +398,40 @@ def click_with_options( - Use `Mouse Button` to click in the center of the element, or the specified position. - Wait for initiated navigation to either succeed or fail, unless the ``noWaitAfter`` option is set. - - | =Arguments= | =Description= | - | ``selector`` | Selector element to click. See the `Finding elements` section for details about the selectors. | - | ``button`` | Mouse button to click with. One of ``left``, ``middle`` or ``right``. Defaults to ``left``. | - | ``*modifiers`` | Modifier keys to press. Ensures that only these modifiers are pressed during the click, and then restores current modifiers back. If not specified, currently pressed modifiers are used. Modifiers can be specified in any order, and multiple modifiers can be specified. Valid modifier keys are ``Alt``, ``Control``, ``ControlOrMeta``, ``Meta`` and ``Shift``. Due to the fact that the argument ``*modifiers`` is a positional only argument, all preceding keyword arguments have to be specified as positional arguments before ``*modifiers``. | - | ``clickCount`` | How many times the button is clicked. Defaults to 1. | - | ``delay`` | Time to wait between mouse-down and mouse-up. Defaults to no delay. | - | ``position_x`` ``position_y`` | A point to click relative to the top-left corner of element bounding-box. Only positive values within the bounding-box are allowed. Both values must be given, otherwise the position is ignored. If not specified, clicks to some visible point of the element. | - | ``force`` | Set to ``True`` to skip Playwright's Actionability checks (https://playwright.dev/docs/actionability). Defaults to ``False``. | - | ``noWaitAfter`` | Deprecated. This option will default to true in the future. Actions that initiate navigation, are waiting for these navigation to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to ``False``. | - | ``trial`` | When set, this method only performs the actionability checks and skips the action. Defaults to ``False``. Useful to wait until the element is ready for the action without performing it. | + *Arguments:* + - ``selector``: Selector element to click. See the `Finding elements` section + for details about the selectors. + - ``button``: Mouse button to click with. One of ``left``, ``middle`` or + ``right``. Defaults to ``left``. + - ``*modifiers``: Modifier keys to press. Ensures that only these modifiers + are pressed during the click, and then restores current modifiers back. + If not specified, currently pressed modifiers are used. Modifiers can be + specified in any order, and multiple modifiers can be specified. Valid + modifier keys are ``Alt``, ``Control``, ``ControlOrMeta``, ``Meta`` and + ``Shift``. Due to the fact that the argument ``*modifiers`` is a + positional only argument, all preceding keyword arguments have to be + specified as positional arguments before ``*modifiers``. + - ``clickCount``: How many times the button is clicked. Defaults to 1. + - ``delay``: Time to wait between mouse-down and mouse-up. Defaults to no + delay. + - ``position_x``: A point to click relative to the top-left corner of element + bounding-box. Only positive values within the bounding-box are allowed. + Both values must be given, otherwise the position is ignored. If not + specified, clicks to some visible point of the element. + - ``position_y``: A point to click relative to the top-left corner of element + bounding-box. Only positive values within the bounding-box are allowed. + Both values must be given, otherwise the position is ignored. If not + specified, clicks to some visible point of the element. + - ``force``: Set to ``True`` to skip Playwright's Actionability checks + (https://playwright.dev/docs/actionability). Defaults to ``False``. + - ``noWaitAfter``: Deprecated. This option will default to true in the future. + Actions that initiate navigation, are waiting for these navigation to + happen and for pages to start loading. You can opt out of waiting via + setting this flag. You would only need this option in the exceptional + cases such as navigating to inaccessible pages. Defaults to ``False``. + - ``trial``: When set, this method only performs the actionability checks and + skips the action. Defaults to ``False``. Useful to wait until the + element is ready for the action without performing it. Arguments ``clickCount``, ``delay``, ``position_x``, ``position_y``, ``force``, ``noWaitAfter`` and ``trial`` are named-only arguments and must be specified using their names. @@ -444,13 +493,29 @@ def tap( - Use page.touchscreen to tap the center of the element, or the specified position. - Wait for initiated navigations to either succeed or fail. - | =Arguments= | =Description= | - | ``selector`` | Selector element to tap. See the `Finding elements` section for details about the selectors. | - | ``*modifiers`` | Modifier keys to press. Ensures that only these modifiers are pressed during the tap, and then restores current modifiers back. If not specified, currently pressed modifiers are used. Modifiers can be specified in any order, and multiple modifiers can be specified. Valid modifier keys are ``Alt``, ``Control``, ``ControlOrMeta``, ``Meta`` and ``Shift``. | - | ``force`` | Whether to bypass the actionability checks. Defaults to ``False``. | - | ``noWaitAfter`` | Deprecated. This option has no effect. Defaults to ``False``. | - | ``position_x`` ``position_y`` | A point to tap relative to the top-left corner of element bounding-box. Only positive values within the bounding-box are allowed. Both values must be given, otherwise the position is ignored. If not specified, taps some visible point of the element. | - | ``trial`` | When set, this method only performs the actionability checks and skips the action. Defaults to ``False``. | + *Arguments:* + - ``selector``: Selector element to tap. See the `Finding elements` section + for details about the selectors. + - ``*modifiers``: Modifier keys to press. Ensures that only these modifiers + are pressed during the tap, and then restores current modifiers back. If + not specified, currently pressed modifiers are used. Modifiers can be + specified in any order, and multiple modifiers can be specified. Valid + modifier keys are ``Alt``, ``Control``, ``ControlOrMeta``, ``Meta`` and + ``Shift``. + - ``force``: Whether to bypass the actionability checks. Defaults to + ``False``. + - ``noWaitAfter``: Deprecated. This option has no effect. Defaults to + ``False``. + - ``position_x``: A point to tap relative to the top-left corner of element + bounding-box. Only positive values within the bounding-box are allowed. + Both values must be given, otherwise the position is ignored. If not + specified, taps some visible point of the element. + - ``position_y``: A point to tap relative to the top-left corner of element + bounding-box. Only positive values within the bounding-box are allowed. + Both values must be given, otherwise the position is ignored. If not + specified, taps some visible point of the element. + - ``trial``: When set, this method only performs the actionability checks and + skips the action. Defaults to ``False``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -489,9 +554,8 @@ def record_selector( ): """Record the selector that is under mouse. - - | =Arguments= | =Description= | - | ``label`` | Text to show in the box on the page while recording. | + *Arguments:* + - ``label``: Text to show in the box on the page while recording. Focus on the page and move the mouse over the element you want to select. @@ -531,12 +595,25 @@ def hover( - Scroll the element into view if needed. - Use `Mouse Move` to hover over the center of the element, or the specified ``position``. - - | =Arguments= | =Description= | - | ``selector`` | Selector element to hover. See the `Finding elements` section for details about the selectors. | - | ``position_x`` & ``position_y`` | A point to hover relative to the top-left corner of element bounding box. If not specified, hovers over some visible point of the element. Only positive values within the bounding-box are allowed. Both values must be given, otherwise the position is ignored. | - | ``force`` | Set to ``True`` to skip Playwright's [https://playwright.dev/docs/actionability|Actionability checks]. Defaults to ``False``. | - | ``*modifiers`` | Modifier keys to press. Ensures that only these modifiers are pressed during the hover, and then restores current modifiers back. If not specified, currently pressed modifiers are used. Valid modifier keys are ``Alt``, ``Control``, ``ControlOrMeta``, ``Meta`` and ``Shift``. | + *Arguments:* + - ``selector``: Selector element to hover. See the `Finding elements` section + for details about the selectors. + - ``position_x``: A point to hover relative to the top-left corner of element + bounding box. If not specified, hovers over some visible point of the + element. Only positive values within the bounding-box are allowed. Both + values must be given, otherwise the position is ignored. + - ``position_y``: A point to hover relative to the top-left corner of element + bounding box. If not specified, hovers over some visible point of the + element. Only positive values within the bounding-box are allowed. Both + values must be given, otherwise the position is ignored. + - ``force``: Set to ``True`` to skip Playwright's + [https://playwright.dev/docs/actionability | Actionability checks]. + Defaults to ``False``. + - ``*modifiers``: Modifier keys to press. Ensures that only these modifiers + are pressed during the hover, and then restores current modifiers back. + If not specified, currently pressed modifiers are used. Valid modifier + keys are ``Alt``, ``Control``, ``ControlOrMeta``, ``Meta`` and + ``Shift``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -567,8 +644,9 @@ def hover( def focus(self, selector: str): """Moves focus on to the element found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the element. See the `Finding elements` section for details about the selectors. | + *Arguments:* + - ``selector``: Selector of the element. See the `Finding elements` section + for details about the selectors. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -596,11 +674,23 @@ def scroll_to( ): """Scrolls an element or the page to an absolute position based on given coordinates. - | =Arguments= | =Description= | - | ``selector`` | Selector of the element. If the selector is ``${None}`` or ``${Empty}`` the page itself is scrolled. To ensure an element is in view use `Hover` instead. See the `Finding elements` section for details about the selectors. | - | ``vertical`` | Defines where to scroll vertically. It can be a positive number, like ``300``. It can be a percentage value of the absolute scrollable size, like ``50%``. It can be a string defining the top or the bottom of the scroll area. < ``top`` | ``bottom`` > _Be aware that some pages do lazy loading and load more content once you scroll down._ Bottom defines the currently known bottom coordinate. Defaults to ``top``. | - | ``horizontal`` | Defines where to scroll horizontally. Works the same way as ``vertical``, but defines < ``left`` | ``right`` > as start and end. Defaults to ``left``. | - | ``behavior`` | Defines whether the scroll happens instantly or smoothly. Defaults to ``auto``. | + *Arguments:* + - ``selector``: Selector of the element. If the selector is ``${None}`` or + ``${Empty}`` the page itself is scrolled. To ensure an element is in + view use `Hover` instead. See the `Finding elements` section for details + about the selectors. + - ``vertical``: Defines where to scroll vertically. It can be a positive + number, like ``300``. It can be a percentage value of the absolute + scrollable size, like ``50%``. It can be a string defining the top or + the bottom of the scroll area. < ``top`` | ``bottom`` > _Be aware that + some pages do lazy loading and load more content once you scroll down._ + Bottom defines the currently known bottom coordinate. Defaults to + ``top``. + - ``horizontal``: Defines where to scroll horizontally. Works the same way as + ``vertical``, but defines < ``left`` | ``right`` > as start and end. + Defaults to ``left``. + - ``behavior``: Defines whether the scroll happens instantly or smoothly. + Defaults to ``auto``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -637,11 +727,26 @@ def scroll_by( ): """Scrolls an element or the page relative from current position by the given values. - | =Arguments= | =Description= | - | ``selector`` | Selector of the element. If the selector is ``${None}`` or ``${Empty}`` the page itself is scrolled. To ensure an element is in view use `Hover` instead. See the `Finding elements` section for details about the selectors. | - | ``vertical`` | Defines how far and in which direction to scroll vertically. It can be a positive or negative number. Positive scrolls down, like ``50``, negative scrolls up, like ``-50``. It can be a percentage value of the absolute scrollable size, like ``9.95%`` or negative like ``-10%``. It can be the string ``height`` to scroll exactly one visible height down, or ``-height`` to scroll one visible height up. _Be aware that some pages do lazy loading and load more content once you scroll down._ The percentage of the current scrollable height is used and may change. Defaults to ``height``. | - | ``horizontal`` | Defines how far and in which direction to scroll horizontally. Works the same way as ``vertical``, but positive values scroll to the right and negative values to the left. ``width`` scrolls exactly one visible range to the right. Defaults to ``0``. | - | ``behavior`` | Defines whether the scroll happens instantly or smoothly. Defaults to ``auto``. | + *Arguments:* + - ``selector``: Selector of the element. If the selector is ``${None}`` or + ``${Empty}`` the page itself is scrolled. To ensure an element is in + view use `Hover` instead. See the `Finding elements` section for details + about the selectors. + - ``vertical``: Defines how far and in which direction to scroll vertically. + It can be a positive or negative number. Positive scrolls down, like + ``50``, negative scrolls up, like ``-50``. It can be a percentage value + of the absolute scrollable size, like ``9.95%`` or negative like + ``-10%``. It can be the string ``height`` to scroll exactly one visible + height down, or ``-height`` to scroll one visible height up. _Be aware + that some pages do lazy loading and load more content once you scroll + down._ The percentage of the current scrollable height is used and may + change. Defaults to ``height``. + - ``horizontal``: Defines how far and in which direction to scroll + horizontally. Works the same way as ``vertical``, but positive values + scroll to the right and negative values to the left. ``width`` scrolls + exactly one visible range to the right. Defaults to ``0``. + - ``behavior``: Defines whether the scroll happens instantly or smoothly. + Defaults to ``auto``. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -673,8 +778,9 @@ def scroll_to_element(self, selector: str): """This method waits for actionability checks, then tries to scroll element into view, unless it is completely visible. - | =Arguments= | =Description= | - | ``selector`` | Selector of the element. See the `Finding elements` section for details about the selectors. | + *Arguments:* + - ``selector``: Selector of the element. See the `Finding elements` section + for details about the selectors. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -693,9 +799,11 @@ def scroll_to_element(self, selector: str): def check_checkbox(self, selector: str, force: bool = False): """Checks the checkbox or selects radio button found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the checkbox. See the `Finding elements` section for details about the selectors. | - | ``force`` | Set to ``True`` to skip Playwright's [https://playwright.dev/docs/actionability|Actionability checks]. | + *Arguments:* + - ``selector``: Selector of the checkbox. See the `Finding elements` section + for details about the selectors. + - ``force``: Set to ``True`` to skip Playwright's + [https://playwright.dev/docs/actionability | Actionability checks]. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -716,9 +824,11 @@ def check_checkbox(self, selector: str, force: bool = False): def uncheck_checkbox(self, selector: str, force: bool = False): """Unchecks the checkbox found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the checkbox. See the `Finding elements` section for details about the selectors. | - | ``force`` | Set to ``True`` to skip Playwright's [https://playwright.dev/docs/actionability|Actionability checks]. | + *Arguments:* + - ``selector``: Selector of the checkbox. See the `Finding elements` section + for details about the selectors. + - ``force``: Set to ``True`` to skip Playwright's + [https://playwright.dev/docs/actionability | Actionability checks]. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -744,10 +854,12 @@ def select_options_by( ) -> list[Any]: """Selects options from select element found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the ```` tag. See the `Finding elements` + section for details about the selectors. + - ``attribute``: Attribute to select options by. Can be ``value``, ``label``, + ``text`` or ``index``. Where ``label`` and ``text`` are same. + - ``*values``: Values to select. Returns a list of the options which the keyword was able to select. The type of @@ -810,8 +922,9 @@ def select_options_by( def deselect_options(self, selector: str): """Deselects all options from select element found by ``selector``. - | =Arguments= | =Description= | - | ``selector`` | Selector of the select tag. See the `Finding elements` section for details about the selectors. | + *Arguments:* + - ``selector``: Selector of the select tag. See the `Finding elements` section + for details about the selectors. If you just want to select one or more specific options and currently more options are selected, use `Select Options By` @@ -889,9 +1002,10 @@ def handle_future_dialogs(self, action: DialogAction, prompt_input: str = ""): Such a failure is reported in the playwright-log.txt file only, which is linked into the Robot Framework log when a keyword fails. - | =Arguments= | =Description= | - | ``action`` | How to handle the alert. Can be ``accept`` or ``dismiss``. | - | ``prompt_input`` | The value to enter into the prompt. Only valid if the ``action`` argument equals ``accept``. Defaults to an empty string. | + *Arguments:* + - ``action``: How to handle the alert. Can be ``accept`` or ``dismiss``. + - ``prompt_input``: The value to enter into the prompt. Only valid if the + ``action`` argument equals ``accept``. Defaults to an empty string. Example: | `Handle Future Dialogs` action=accept @@ -920,11 +1034,13 @@ def wait_for_alert( Dialog/alert can be any of alert, beforeunload, confirm or prompt. - | =Arguments= | =Description= | - | ``action`` | How to handle the alert. Can be ``accept`` or ``dismiss``. | - | ``prompt_input`` | The value to enter into the prompt. Only valid if the ``action`` argument equals ``accept``. Defaults to an empty string. | - | ``text`` | Optional text to verify the dialog text with. | - | ``timeout`` | Optional timeout in Robot Framework time format. Defaults to the library timeout. | + *Arguments:* + - ``action``: How to handle the alert. Can be ``accept`` or ``dismiss``. + - ``prompt_input``: The value to enter into the prompt. Only valid if the + ``action`` argument equals ``accept``. Defaults to an empty string. + - ``text``: Optional text to verify the dialog text with. + - ``timeout``: Optional timeout in Robot Framework time format. Defaults to + the library timeout. The main difference between this keyword and `Handle Future Dialogs` @@ -971,11 +1087,16 @@ def wait_for_alerts( Handles each alert/dialog with ``actions`` and optionally verifies the dialog texts. Dialog/alert can be any of alert, beforeunload, confirm or prompt. - | =Arguments= | =Description= | - | ``actions`` | List of how to handle the alerts. Can be ``accept`` or ``dismiss``. | - | ``prompt_inputs`` | List of the values to enter into the prompts. Only valid if the corresponding action equals ``accept``. Use ``None`` if no input is needed. | - | ``texts`` | List of optional texts to verify the dialog texts with. Use ``None`` if text verification should be disabled. | - | ``timeout`` | Optional timeout in Robot Framework time format. Defaults to the library timeout. The timeout is applied to each alert separately. | + *Arguments:* + - ``actions``: List of how to handle the alerts. Can be ``accept`` or + ``dismiss``. + - ``prompt_inputs``: List of the values to enter into the prompts. Only valid + if the corresponding action equals ``accept``. Use ``None`` if no input + is needed. + - ``texts``: List of optional texts to verify the dialog texts with. Use + ``None`` if text verification should be disabled. + - ``timeout``: Optional timeout in Robot Framework time format. Defaults to + the library timeout. The timeout is applied to each alert separately. There must be an equal amount of items in the ``actions``, ``prompt_inputs`` and ``texts`` lists. Use ``None`` if texts and/or prompt inputs are not needed. @@ -1047,12 +1168,19 @@ def mouse_button( # ruff: ignore[PLR0917] ): """Clicks, presses or releases a mouse button. - | =Arguments= | =Description= | - | ``action`` | Defines if it is a mouseclick (``click``), holding down a button (``down``) or releasing it (``up``). | - | ``x``, ``y`` | Coordinates to move to before the action is executed. Both must be given, otherwise the action happens at the current mouse position. | - | ``button`` | One of ``left``, ``middle`` or ``right``. Defaults to ``left``. | - | ``clickCount`` | Determines how often the button shall be clicked if action is equal to ``click``. Defaults to 1. | - | ``delay`` | Delay in Robot Framework time format between the mousedown and mouseup event. Can only be set if the action is ``click``. Defaults to ``0 s``. | + *Arguments:* + - ``action``: Defines if it is a mouseclick (``click``), holding down a button + (``down``) or releasing it (``up``). + - ``x``: Coordinates to move to before the action is executed. Both must be + given, otherwise the action happens at the current mouse position. + - ``y``: Coordinates to move to before the action is executed. Both must be + given, otherwise the action happens at the current mouse position. + - ``button``: One of ``left``, ``middle`` or ``right``. Defaults to ``left``. + - ``clickCount``: Determines how often the button shall be clicked if action + is equal to ``click``. Defaults to 1. + - ``delay``: Delay in Robot Framework time format between the mousedown and + mouseup event. Can only be set if the action is ``click``. Defaults to + ``0 s``. *Attention:* Argument type ``int`` for 'delay' in milliseconds has been changed to `timedelta` in Browser 14.0.0. Use Robot Framework time format instead. @@ -1113,10 +1241,12 @@ def drag_and_drop( """Executes a Drag&Drop operation from the element selected by ``selector_from`` to the element selected by ``selector_to``. - | =Arguments= | =Description= | - | ``selector_from`` | Identifies the element whose center is the start-point. | - | ``selector_to`` | Identifies the element whose center is the end-point. | - | ``steps`` | Defines how many intermediate mouse move events are sent. Often it is necessary to send more than one intermediate event to get the desired result. Defaults to 1. | + *Arguments:* + - ``selector_from``: Identifies the element whose center is the start-point. + - ``selector_to``: Identifies the element whose center is the end-point. + - ``steps``: Defines how many intermediate mouse move events are sent. Often + it is necessary to send more than one intermediate event to get the + desired result. Defaults to 1. See the `Finding elements` section for details about the selectors. @@ -1167,10 +1297,14 @@ def drag_and_drop_by_coordinates( Start- and end-point are defined by ``x`` and ``y`` coordinates relative to the top left corner of the pages viewport. - | =Arguments= | =Description= | - | ``from_x`` & ``from_y`` | Identify the start-point on page. | - | ``to_x`` & ``to_y`` | Identify the end-point. | - | ``steps`` | Defines how many intermediate mouse move events are sent. Often it is necessary to send more than one intermediate event to get the desired result. Defaults to 1. | + *Arguments:* + - ``from_x``: Identify the start-point on page. + - ``from_y``: Identify the start-point on page. + - ``to_x``: Identify the end-point. + - ``to_y``: Identify the end-point. + - ``steps``: Defines how many intermediate mouse move events are sent. Often + it is necessary to send more than one intermediate event to get the + desired result. Defaults to 1. Example: | `Drag And Drop By Coordinates` @@ -1196,10 +1330,13 @@ def drag_and_drop_relative_to( This keyword can be handy to simulate swipe actions. - | =Arguments= | =Description= | - | ``selector_from`` | Identifies the element whose center is the start-point. | - | ``x`` & ``y`` | Identify the end-point, which is relative to the start-point. | - | ``steps`` | Defines how many intermediate mouse move events are sent. Often it is necessary to send more than one intermediate event to get the desired result. Defaults to 1. | + *Arguments:* + - ``selector_from``: Identifies the element whose center is the start-point. + - ``x``: Identify the end-point, which is relative to the start-point. + - ``y``: Identify the end-point, which is relative to the start-point. + - ``steps``: Defines how many intermediate mouse move events are sent. Often + it is necessary to send more than one intermediate event to get the + desired result. Defaults to 1. See the `Finding elements` section for details about the selectors. @@ -1243,10 +1380,13 @@ def mouse_move_relative_to( ): """Moves the mouse cursor relative to the selected element. - | =Arguments= | =Description= | - | ``selector`` | Identifies the element whose center is the start-point. | - | ``x`` & ``y`` | Coordinates relative to the center of the element's bounding box. | - | ``steps`` | Number of intermediate steps for the mouse event. Often it is necessary to send more than one intermediate event to get the desired result. Defaults to 1. | + *Arguments:* + - ``selector``: Identifies the element whose center is the start-point. + - ``x``: Coordinates relative to the center of the element's bounding box. + - ``y``: Coordinates relative to the center of the element's bounding box. + - ``steps``: Number of intermediate steps for the mouse event. Often it is + necessary to send more than one intermediate event to get the desired + result. Defaults to 1. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -1282,9 +1422,12 @@ def mouse_move(self, x: float, y: float, steps: int = 1): The virtual mouse is left on the specified coordinates. - | =Arguments= | =Description= | - | ``x`` & ``y`` | Absolute coordinates starting at the top left of the page. | - | ``steps`` | Number of intermediate steps for the mouse event. Often it is necessary to send more than one intermediate event to get the desired result. Defaults to 1. | + *Arguments:* + - ``x``: Absolute coordinate starting at the left border of the page. + - ``y``: Absolute coordinate down starting at the top border of the page. + - ``steps``: Number of intermediate steps for the mouse event. Often it is + necessary to send more than one intermediate event to get the desired + result. Defaults to 1. Example: | `Mouse Move` 400 400 @@ -1301,8 +1444,9 @@ def mouse_move(self, x: float, y: float, steps: int = 1): def mouse_wheel(self, deltaX: int, deltaY: int): """Simulates the user rotation of a mouse wheel. - | =Arguments= | =Description= | - | ``deltaX`` & ``deltaY`` | Pixels that are scrolled horizontally & vertically. | + *Arguments:* + - ``deltaX``: Pixels that are scrolled horizontally. + - ``deltaY``: Pixels that are scrolled vertically. Example: | # Before doing a mouse wheel interaction. A mouse needs to be positioned on the browser window. @@ -1323,10 +1467,18 @@ def keyboard_key( ): """Press a keyboard key on the virtual keyboard or set a key up or down. - | =Arguments= | =Description= | - | ``action`` | Determines whether the key should be released (``up``), held down (``down``) or pressed once (``press``). ``down`` and ``up`` are useful for combinations, i.e. with Shift. | - | ``key`` | The key to be pressed. Examples of valid keys are: ``F1`` - ``F12``, ``Digit0`` - ``Digit9``, ``KeyA`` - ``KeyZ``, ``Backquote``, ``Minus``, ``Equal``, ``Backslash``, ``Backspace``, ``Tab``, ``Delete``, ``Escape``, ``ArrowDown``, ``End``, ``Enter``, ``Home``, ``Insert``, ``PageDown``, ``PageUp``, ``ArrowRight``, ``ArrowUp`` , etc. | - | ``delay`` | Time the key is held down between keydown and keyup, in Robot Framework's time format. Only valid with action ``press``, other actions raise an error. Defaults to ``0 s``. Example: ``50 ms`` | + *Arguments:* + - ``action``: Determines whether the key should be released (``up``), held + down (``down``) or pressed once (``press``). ``down`` and ``up`` are + useful for combinations, i.e. with Shift. + - ``key``: The key to be pressed. Examples of valid keys are: ``F1`` - + ``F12``, ``Digit0`` - ``Digit9``, ``KeyA`` - ``KeyZ``, ``Backquote``, + ``Minus``, ``Equal``, ``Backslash``, ``Backspace``, ``Tab``, ``Delete``, + ``Escape``, ``ArrowDown``, ``End``, ``Enter``, ``Home``, ``Insert``, + ``PageDown``, ``PageUp``, ``ArrowRight``, ``ArrowUp`` , etc. + - ``delay``: Time the key is held down between keydown and keyup, in Robot + Framework's time format. Only valid with action ``press``, other actions + raise an error. Defaults to ``0 s``. Example: ``50 ms`` Useful keys for ``down`` and ``up`` for example are: @@ -1366,10 +1518,13 @@ def keyboard_input( ): """Input text into page with virtual keyboard. - | =Arguments= | =Description= | - | ``action`` | ``insertText``: Dispatches only input event, does not emit the keydown, keyup or keypress events. ``type``: Sends a keydown, keypress/input, and keyup event for each character in the text. | - | ``input`` | The input string to be typed. _No special keys possible._ | - | ``delay`` | Time to wait between key presses in Robot Framework's time format. Defaults to ``0 ms``. | + *Arguments:* + - ``action``: ``insertText``: Dispatches only input event, does not emit the + keydown, keyup or keypress events. ``type``: Sends a keydown, + keypress/input, and keyup event for each character in the text. + - ``input``: The input string to be typed. _No special keys possible._ + - ``delay``: Time to wait between key presses in Robot Framework's time + format. Defaults to ``0 ms``. *Attention:* Argument type ``int`` for 'delay' in milliseconds has been changed to `timedelta` in Browser 14.0.0. Use Robot Framework time format with units instead. @@ -1424,10 +1579,11 @@ def upload_file_by_selector( Keyword uses strict mode, see `Finding elements` for more details about strict mode. - | =Arguments= | =Description= | - | ``selector`` | Identifies the file input element. | - | ``path`` | Path to the file or folder to be uploaded. Can also be a `FileUploadBuffer` dictionary. | - | ``extra_paths`` | Additional paths to files or folders to be uploaded. | + *Arguments:* + - ``selector``: Identifies the file input element. + - ``path``: Path to the file or folder to be uploaded. Can also be a + `FileUploadBuffer` dictionary. + - ``extra_paths``: Additional paths to files or folders to be uploaded. If ``path`` is a `FileUploadBuffer` dictionary, then the structure should be: | { diff --git a/Browser/keywords/locator_handler.py b/Browser/keywords/locator_handler.py index 69ab6a7c5..bb7c70182 100644 --- a/Browser/keywords/locator_handler.py +++ b/Browser/keywords/locator_handler.py @@ -45,14 +45,22 @@ def add_locator_handler_click( [https://playwright.dev/docs/api/class-page#page-add-locator-handler|addLocatorHandler] method. - | =Arguments= | =Description= | - | ``selector`` | Is the selector to the element which indicates that the locator handler should be called. | - | ``noWaitAfter`` | Defaults to ``True``, which means that the overlay may stay visible after the handler has run. If set to ``False``, Playwright waits until the overlay becomes hidden, and only then the library continues with the action/assertion that triggered the handler. | - | ``times`` | Is how many times the locator handler is called. ``None``, the default, means unlimited. | - | ``click_selector`` | Is the selector to the element to be clicked. | - | ``click_clickCount`` | Is the number of times to click the element. Defaults to 1. | - | ``click_delay`` | Time to wait between mousedown and mouseup in milliseconds. Defaults to 0. | - | ``click_force`` | Whether to bypass checks and dispatch the event directly. Defaults to false. | + *Arguments:* + - ``selector``: Is the selector to the element which indicates that the + locator handler should be called. + - ``noWaitAfter``: Defaults to ``True``, which means that the overlay may stay + visible after the handler has run. If set to ``False``, Playwright waits + until the overlay becomes hidden, and only then the library continues + with the action/assertion that triggered the handler. + - ``times``: Is how many times the locator handler is called. ``None``, the + default, means unlimited. + - ``click_selector``: Is the selector to the element to be clicked. + - ``click_clickCount``: Is the number of times to click the element. Defaults + to 1. + - ``click_delay``: Time to wait between mousedown and mouseup in milliseconds. + Defaults to 0. + - ``click_force``: Whether to bypass checks and dispatch the event directly. + Defaults to false. The arguments ``click_selector``, ``click_clickCount``, ``click_delay`` and ``click_force`` correspond to the arguments of the `Click With Options` keyword, but ``click_delay`` is given @@ -117,11 +125,17 @@ def add_locator_handler_custom( When the element indicated by ``selector`` is visible, the handler will perform the actions specified in the ``handler_spec``. - | =Arguments= | =Description= | - | ``selector`` | Is the selector to the element which indicates that the locator handler should be called. | - | ``handler_spec`` | Is a list of dictionaries which defines the actions to be performed. | - | ``noWaitAfter`` | Defaults to ``True``, which means that the overlay may stay visible after the handler has run. If set to ``False``, Playwright waits until the overlay becomes hidden, and only then the library continues with the action/assertion that triggered the handler. | - | ``times`` | Is how many times the locator handler is called. ``None``, the default, means unlimited. | + *Arguments:* + - ``selector``: Is the selector to the element which indicates that the + locator handler should be called. + - ``handler_spec``: Is a list of dictionaries which defines the actions to be + performed. + - ``noWaitAfter``: Defaults to ``True``, which means that the overlay may stay + visible after the handler has run. If set to ``False``, Playwright waits + until the overlay becomes hidden, and only then the library continues + with the action/assertion that triggered the handler. + - ``times``: Is how many times the locator handler is called. ``None``, the + default, means unlimited. The ``handler_spec`` is a list of dictionaries, where each dictionary defines one action. The dictionary must contain the key ``action`` which defines the action to be diff --git a/Browser/keywords/network.py b/Browser/keywords/network.py index 7cd4a035d..7f4fb6d79 100644 --- a/Browser/keywords/network.py +++ b/Browser/keywords/network.py @@ -68,11 +68,15 @@ def http( The request is sent with the browser's ``fetch`` from the currently active page, so a relative ``url`` is resolved against the URL of that page. - | =Arguments= | =Description= | - | ``url`` | The request url, e.g. ``/api/foo``. | - | ``method`` | The HTTP method for the request. Defaults to GET. | - | ``body`` | The request body. It is ignored for GET requests, because GET requests cannot have a body. If the body can be parsed as JSON, the ``Content-Type`` header for the request is automatically set to ``application/json``, unless ``headers`` already contains that header. Defaults to None. | - | ``headers`` | A dictionary of additional request headers. Defaults to None. | + *Arguments:* + - ``url``: The request url, e.g. ``/api/foo``. + - ``method``: The HTTP method for the request. Defaults to GET. + - ``body``: The request body. It is ignored for GET requests, because GET + requests cannot have a body. If the body can be parsed as JSON, the + ``Content-Type`` header for the request is automatically set to + ``application/json``, unless ``headers`` already contains that header. + Defaults to None. + - ``headers``: A dictionary of additional request headers. Defaults to None. The response is a Robot Framework dictionary with the following attributes: - ``status`` The status code of the response. @@ -163,9 +167,17 @@ def wait_for_request( ``headers`` is a dictionary of request headers. ``postData`` is ``None`` if the request has no body, a dictionary if the body is valid JSON and otherwise the body as a string. - | =Arguments= | =Description= | - | ``matcher`` | Request URL matcher. Can be a string (Glob-Pattern), a JavaScript RegExp (enclosed in ``/`` with optional trailing flags) or a JavaScript arrow-function that receives the [https://playwright.dev/docs/api/class-request|Request] object and returns a boolean. By default (with an empty string) the first request is matched. For additional information, see the Playwright [https://playwright.dev/docs/api/class-page#page-wait-for-request|waitForRequest] documentation. | - | ``timeout`` | Timeout supports Robot Framework time format. Uses default timeout if not set. | + *Arguments:* + - ``matcher``: Request URL matcher. Can be a string (Glob-Pattern), a + JavaScript RegExp (enclosed in ``/`` with optional trailing flags) or a + JavaScript arrow-function that receives the + [https://playwright.dev/docs/api/class-request | Request] object and + returns a boolean. By default (with an empty string) the first request + is matched. For additional information, see the Playwright + [https://playwright.dev/docs/api/class-page#page-wait-for-request | + waitForRequest] documentation. + - ``timeout``: Timeout supports Robot Framework time format. Uses default + timeout if not set. See `Wait For Response` for more details about the matcher. @@ -203,9 +215,16 @@ def wait_for_response( - ``request`` containing ``method`` , ``headers`` and ``postData`` | - ``url`` url of the response. - | =Arguments= | =Description= | - | ``matcher`` | Response URL matcher. Can be a string (Glob-Pattern), a JavaScript RegExp (enclosed in ``/`` with optional trailing flags) or a JavaScript arrow-function that receives the Response object and returns a boolean. By default (with an empty string) the first response is matched. For additional information, see the Playwright [https://playwright.dev/docs/api/class-page#page-wait-for-response|page.waitForResponse] documentation. | - | ``timeout`` | Timeout supports Robot Framework time format. Uses default timeout if not set. | + *Arguments:* + - ``matcher``: Response URL matcher. Can be a string (Glob-Pattern), a + JavaScript RegExp (enclosed in ``/`` with optional trailing flags) or a + JavaScript arrow-function that receives the Response object and returns + a boolean. By default (with an empty string) the first response is + matched. For additional information, see the Playwright + [https://playwright.dev/docs/api/class-page#page-wait-for-response | + page.waitForResponse] documentation. + - ``timeout``: Timeout supports Robot Framework time format. Uses default + timeout if not set. *CAUTION:* Before Browser library 17.0.0, the ``matcher`` argument was always either a regex or JS function. But the regex did not need to be in slashes. @@ -281,11 +300,19 @@ def wait_for_navigation( ): """Waits until the page has navigated to the given ``url``. - - | =Arguments= | =Description= | - | ``url`` | Expected navigation target address, either a Glob-Pattern (a plain string without wildcards matches exactly) or a JavaScript-like regex wrapped in ``/`` symbols. | - | ``timeout`` | Timeout supports Robot Framework time format. Uses default timeout if not set. | - | ``wait_until`` | When to consider the operation succeeded, defaults to load. Events can be either: ``domcontentloaded`` - consider operation to be finished when the DOMContentLoaded event is fired. ``load`` - consider operation to be finished when the load event is fired. ``networkidle`` - consider operation to be finished when there are no network connections for at least 500 ms. ``commit`` - consider operation to be finished when network response is received and the document started loading. | + *Arguments:* + - ``url``: Expected navigation target address, either a Glob-Pattern (a plain + string without wildcards matches exactly) or a JavaScript-like regex + wrapped in ``/`` symbols. + - ``timeout``: Timeout supports Robot Framework time format. Uses default + timeout if not set. + - ``wait_until``: When to consider the operation succeeded, defaults to load. + Events can be either: ``domcontentloaded`` - consider operation to be + finished when the DOMContentLoaded event is fired. ``load`` - consider + operation to be finished when the load event is fired. ``networkidle`` - + consider operation to be finished when there are no network connections + for at least 500 ms. ``commit`` - consider operation to be finished when + network response is received and the document started loading. The keyword works only when the page is loaded and it does not work if only the URL fragment changes. Example: if diff --git a/Browser/keywords/pdf.py b/Browser/keywords/pdf.py index 4ce0325dd..b309af79f 100644 --- a/Browser/keywords/pdf.py +++ b/Browser/keywords/pdf.py @@ -63,22 +63,35 @@ def save_page_as_pdf( Saving a PDF is currently only supported in Chromium and only when the browser is running in headless mode. - | =Arguments= | =Description= | - | ``path`` | Where the PDF is saved. If the path is not absolute, the file is saved relative to ${OUTPUT_DIR}. | - | ``displayHeaderFooter`` | Display header and footer. Defaults to false. | - | ``footerTemplate`` | HTML template for the print footer. Should use the same format as the ``headerTemplate``. | - | ``format`` | Paper format. If set, takes priority over the ``width`` and ``height`` arguments. Defaults to ``Letter``. | - | ``headerTemplate`` | HTML template for the print header. Both templates are only rendered when ``displayHeaderFooter`` is true. See the detailed explanation below. | - | ``height`` | Paper height, accepts values labeled with units. | - | ``landscape`` | Paper orientation. Defaults to false. | - | ``margin`` | Defines the PDF margins, see `PdfMarging` for more details. Defaults to ``0px`` on all sides. | - | ``outline`` | Whether or not to embed the document outline into the PDF. Defaults to false. | - | ``pageRanges`` | Paper ranges to print, e.g. ``1-5, 8, 11-13``. Defaults to the empty string, which means print all pages. | - | ``preferCSSPageSize`` | Give any CSS ``@page`` size declared in the page priority over what is declared in the ``width`` and ``height`` or ``format`` arguments. Defaults to false, which will scale the content to fit the paper size. | - | ``printBackground`` | Print background graphics. Defaults to false. | - | ``scale`` | Scale of the webpage rendering. Defaults to 1. Scale amount must be between 0.1 and 2. | - | ``tagged`` | Whether or not to generate a tagged (accessible) PDF. Defaults to false. | - | ``width`` | Paper width, accepts values labeled with units. | + *Arguments:* + - ``path``: Where the PDF is saved. If the path is not absolute, the file is + saved relative to ${OUTPUT_DIR}. + - ``displayHeaderFooter``: Display header and footer. Defaults to false. + - ``footerTemplate``: HTML template for the print footer. Should use the same + format as the ``headerTemplate``. + - ``format``: Paper format. If set, takes priority over the ``width`` and + ``height`` arguments. Defaults to ``Letter``. + - ``headerTemplate``: HTML template for the print header. Both templates are + only rendered when ``displayHeaderFooter`` is true. See the detailed + explanation below. + - ``height``: Paper height, accepts values labeled with units. + - ``landscape``: Paper orientation. Defaults to false. + - ``margin``: Defines the PDF margins, see `PdfMarging` for more details. + Defaults to ``0px`` on all sides. + - ``outline``: Whether or not to embed the document outline into the PDF. + Defaults to false. + - ``pageRanges``: Paper ranges to print, e.g. ``1-5, 8, 11-13``. Defaults to + the empty string, which means print all pages. + - ``preferCSSPageSize``: Give any CSS ``@page`` size declared in the page + priority over what is declared in the ``width`` and ``height`` or + ``format`` arguments. Defaults to false, which will scale the content to + fit the paper size. + - ``printBackground``: Print background graphics. Defaults to false. + - ``scale``: Scale of the webpage rendering. Defaults to 1. Scale amount must + be between 0.1 and 2. + - ``tagged``: Whether or not to generate a tagged (accessible) PDF. Defaults + to false. + - ``width``: Paper width, accepts values labeled with units. ``headerTemplate`` and ``footerTemplate`` should be valid HTML markup. The following classes can be used to inject printing values into them: @@ -167,11 +180,19 @@ def emulate_media( This is useful to render the page in the correct format before using the `Save Page As Pdf` keyword. - | =Arguments= | =Description= | - | ``colorScheme`` | Emulates the ``prefers-color-scheme`` media feature, supported values are ``light`` and ``dark``. Passing ``null`` disables color scheme emulation. ``no-preference`` is deprecated. | - | ``forcedColors`` | Emulates the ``forced-colors`` media feature, supported values are ``active`` and ``none``. Passing ``null`` disables forced colors emulation. | - | ``media`` | Changes the CSS media type of the page. The only allowed values are ``screen``, ``print`` and ``null``. Passing ``null`` disables CSS media emulation. | - | ``reducedMotion`` | Emulates the ``prefers-reduced-motion`` media feature, supported values are ``reduce`` and ``no-preference``. Passing ``null`` disables reduced motion emulation. | + *Arguments:* + - ``colorScheme``: Emulates the ``prefers-color-scheme`` media feature, + supported values are ``light`` and ``dark``. Passing ``null`` disables + color scheme emulation. ``no-preference`` is deprecated. + - ``forcedColors``: Emulates the ``forced-colors`` media feature, supported + values are ``active`` and ``none``. Passing ``null`` disables forced + colors emulation. + - ``media``: Changes the CSS media type of the page. The only allowed values + are ``screen``, ``print`` and ``null``. Passing ``null`` disables CSS + media emulation. + - ``reducedMotion``: Emulates the ``prefers-reduced-motion`` media feature, + supported values are ``reduce`` and ``no-preference``. Passing ``null`` + disables reduced motion emulation. Arguments which are left to their default value are not sent to Playwright at all and therefore the corresponding emulation is left unchanged. diff --git a/Browser/keywords/playwright_state.py b/Browser/keywords/playwright_state.py index 48076f6b3..1ee838ff5 100755 --- a/Browser/keywords/playwright_state.py +++ b/Browser/keywords/playwright_state.py @@ -81,20 +81,23 @@ def open_browser( pause_on_failure: bool = True, bypassCSP=True, ): - """Opens a new browser instance. Use this keyword for quick experiments or debugging sessions. + """*DEPRECATED* Opens a new browser instance. Use this keyword for quick experiments or debugging sessions. Use `New Page` directly instead of `Open Browser` for production and automated execution. See `Browser, Context and Page` for more information about Browser and related concepts. Creates a new browser, context and page with specified settings. - - | =Argument= | =Description= | - | ``url`` | Navigates to URL if provided. Defaults to None. | - | ``browser`` | Specifies which browser to use. The supported browsers are listed in the table below. | - | ``headless`` | If set to False, a GUI is provided otherwise it is hidden. Defaults to False. | - | ``pause_on_failure`` | Stop execution when failure detected and leave browser open. Defaults to True. | - | ``bypassCSP`` | Defaults to bypassing CSP and enabling custom script attach to the page. | + *Arguments:* + - ``url``: Navigates to URL if provided. Defaults to None. + - ``browser``: Specifies which browser to use. The supported browsers are + listed in the table below. + - ``headless``: If set to False, a GUI is provided otherwise it is hidden. + Defaults to False. + - ``pause_on_failure``: Stop execution when failure detected and leave browser + open. Defaults to True. + - ``bypassCSP``: Defaults to bypassing CSP and enabling custom script attach + to the page. Browsers: @@ -122,9 +125,10 @@ def close_browser(self, browser: SelectionType | str = SelectionType.CURRENT): to this browser. See `Browser, Context and Page` for more information about Browser and related concepts. - - | =Argument= | =Description= | - | ``browser`` | Browser to close. ``CURRENT`` selects the active browser. ``ALL`` closes all browsers. When a browser id is provided, that browser is closed. | + *Arguments:* + - ``browser``: Browser to close. ``CURRENT`` selects the active browser. + ``ALL`` closes all browsers. When a browser id is provided, that browser + is closed. @@ -179,10 +183,16 @@ def close_context( Active context is set to the context that was active before this one. Closes pages belonging to this context. See `Browser, Context and Page` for more information about Context and related concepts. - | =Argument= | =Description= | - | ``context`` | Context to close. ``CURRENT`` selects the active context. ``ALL`` selects all contexts. When a context id is provided, that context is closed. | - | ``browser`` | Browser in which contexts are closed. ``CURRENT`` selects the active browser. ``ALL`` selects all browsers. When a browser id is provided, contexts of that browser are closed. The browsers themselves are not closed. | - | ``save_trace`` | If set to ``False``, the trace of this context is not saved, even if it was enabled by `New Context`. Defaults to ``True``. | + *Arguments:* + - ``context``: Context to close. ``CURRENT`` selects the active context. + ``ALL`` selects all contexts. When a context id is provided, that + context is closed. + - ``browser``: Browser in which contexts are closed. ``CURRENT`` selects the + active browser. ``ALL`` selects all browsers. When a browser id is + provided, contexts of that browser are closed. The browsers themselves + are not closed. + - ``save_trace``: If set to ``False``, the trace of this context is not saved, + even if it was enabled by `New Context`. Defaults to ``True``. Example: | `Close Context` # Closes the current context of the current browser @@ -288,15 +298,20 @@ def close_page( Defaults to current for all three. Active page is set to the page that was active before this one. See `Browser, Context and Page` for more information about Page and related concepts. - ``runBeforeUnload`` defines where to run the - [https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event|before unload] - page handlers. Defaults to false. - - - | =Argument= | =Description= | - | ``page`` | Page to close. ``CURRENT`` selects the active page. ``ALL`` selects all pages. When a page id is provided, that page is closed. | - | ``context`` | Context in which pages are closed. ``CURRENT`` selects the active context. ``ALL`` selects all contexts. When a context id is provided, pages of that context are closed. The contexts themselves are not closed. | - | ``browser`` | Browser in which pages are closed. ``CURRENT`` selects the active browser. ``ALL`` selects all browsers. When a browser id is provided, pages of that browser are closed. The browsers themselves are not closed. | + *Arguments:* + - ``page``: Page to close. ``CURRENT`` selects the active page.``ALL`` + selects all pages. When a page id is provided, that page is closed. + - ``context``: Context in which pages are closed. ``CURRENT`` selects the + active context. ``ALL`` selects all contexts. When a context id is + provided, pages of that context are closed. The contexts themselves are + not closed. + - ``browser``: Browser in which pages are closed. ``CURRENT`` selects the + active browser. ``ALL`` selects all browsers. When a browser id is + provided, pages of that browser are closed. The browsers themselves are + not closed. + - ``runBeforeUnload``: defines where to run the + [https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event|before unload] + page handlers. Defaults to false. If a page id is given, the ``context`` and ``browser`` arguments are ignored and the page is searched from all open browsers. Likewise, if a context id is given, the ``browser`` @@ -407,11 +422,15 @@ def connect_to_browser( Returns a stable identifier for the connected browser. - | =Argument= | =Description= | - | ``wsEndpoint`` | Address to connect to. Either ``ws://`` or ``http://`` if cdp is used. | - | ``browser`` | Opens the specified browser. Defaults to ``chromium``. | - | ``use_cdp`` | Connect to browser via Chrome DevTools Protocol. Defaults to False. Works only with Chromium based browsers. | - | ``timeout`` | Maximum time in Robot Framework time format to wait for the connection to be established. Defaults to 30 seconds. The timeout can not be disabled; ``0`` also means 30 seconds. | + *Arguments:* + - ``wsEndpoint``: Address to connect to. Either ``ws://`` or ``http://`` if + cdp is used. + - ``browser``: Opens the specified browser. Defaults to ``chromium``. + - ``use_cdp``: Connect to browser via Chrome DevTools Protocol. Defaults to + False. Works only with Chromium based browsers. + - ``timeout``: Maximum time in Robot Framework time format to wait for the + connection to be established. Defaults to 30 seconds. The timeout can + not be disabled; ``0`` also means 30 seconds. To connect to a browser via Chrome DevTools Protocol, the browser must be started with this protocol enabled. This is typically done by starting a Chrome browser with the argument ``--remote-debugging-port=9222`` or similar. @@ -463,25 +482,59 @@ def new_browser( Returns a stable identifier for the created browser. - | =Arguments= | =Description= | - | ``browser`` | Opens the specified [#type-SupportedBrowsers|browser]. Defaults to chromium. | - | ``headless`` | Set to False if you want a GUI. Defaults to True. | - | ``args`` | Additional arguments to pass to the browser instance. The list of Chromium flags can be found [http://peter.sh/experiments/chromium-command-line-switches/|here]. Defaults to None. | - | ``channel`` | Allows operating against the stock Google Chrome and Microsoft Edge browsers. Can only be used together with the ``chromium`` browser, otherwise the keyword fails. For more details see: [https://playwright.dev/docs/browsers#google-chrome--microsoft-edge|Playwright documentation]. | - | ``chromiumSandbox`` | Enable Chromium sandboxing. Defaults to False. | - | ``devtools`` | Chromium-only. Whether to auto-open a Developer Tools panel for each tab. Defaults to False. | - | ``downloadsPath`` | If specified, accepted downloads are downloaded into this folder. Otherwise, temporary folder is created and is deleted when browser is closed. Regarding file deletion, see the docs of `Download` and `Promise To Wait For Download`. | - | ``env`` | Specifies environment variables that will be visible to the browser. Dictionary keys are variable names, values are the content. Defaults to None. | - | ``executablePath`` | Path to a browser executable to run instead of the bundled one. If executablePath is a relative path, then it is resolved relative to current working directory. Note that Playwright only works with the bundled Chromium, Firefox or WebKit, use at your own risk. Defaults to None. | - | ``firefoxUserPrefs`` | Firefox user preferences. Learn more about the Firefox user preferences at [https://support.mozilla.org/en-US/kb/about-config-editor-firefox|about:config]. | - | ``handleSIGHUP`` | Close the browser process on SIGHUP. Defaults to True. | - | ``handleSIGINT`` | Close the browser process on Ctrl-C. Defaults to True. | - | ``handleSIGTERM`` | Close the browser process on SIGTERM. Defaults to True. | - | ``ignoreDefaultArgs`` | If True, Playwright does not pass its own configuration args and only uses the ones from ``args``. If a list is given, then the given default arguments are filtered out. Dangerous option; use with care. Defaults to None, which means Playwright's own default arguments are used. | - | ``proxy`` | Network [#type-Proxy|Proxy] settings. Structure: ``{'server': , 'bypass': , 'username': , 'password': }``. Robot Framework 7.4 Secret type is supported.` | - | ``reuse_existing`` | If set to True, an existing browser instance that was created with the same arguments is reused. If no such browser exists, a new one is started. Defaults to True. | - | ``slowMo`` | Slows down Playwright operations by the given time, in Robot Framework time format. Useful so that you can see what is going on. Defaults to no delay. | - | ``timeout`` | Maximum time in Robot Framework time format to wait for the browser instance to start. Defaults to 30 seconds. Pass 0 to disable timeout. | + *Arguments:* + - ``browser``: Opens the specified [#type-SupportedBrowsers | browser]. + Defaults to chromium. + - ``headless``: Set to False if you want a GUI. Defaults to True. + - ``args``: Additional arguments to pass to the browser instance. The list of + Chromium flags can be found + [http://peter.sh/experiments/chromium-command-line-switches/ | here]. + Defaults to None. + - ``channel``: Allows operating against the stock Google Chrome and Microsoft + Edge browsers. Can only be used together with the ``chromium`` browser, + otherwise the keyword fails. For more details see: + [https://playwright.dev/docs/browsers#google-chrome--microsoft-edge | + Playwright documentation]. + - ``chromiumSandbox``: Enable Chromium sandboxing. Defaults to False. + - ``devtools``: Chromium-only. Whether to auto-open a Developer Tools panel + for each tab. Defaults to False. + - ``downloadsPath``: If specified, accepted downloads are downloaded into this + folder. Otherwise, temporary folder is created and is deleted when + browser is closed. Regarding file deletion, see the docs of `Download` + and `Promise To Wait For Download`. + - ``env``: Specifies environment variables that will be visible to the + browser. Dictionary keys are variable names, values are the content. + Defaults to None. + - ``executablePath``: Path to a browser executable to run instead of the + bundled one. If executablePath is a relative path, then it is resolved + relative to current working directory. Note that Playwright only works + with the bundled Chromium, Firefox or WebKit, use at your own risk. + Defaults to None. + - ``firefoxUserPrefs``: Firefox user preferences. Learn more about the Firefox + user preferences at + [https://support.mozilla.org/en-US/kb/about-config-editor-firefox | + about:config]. + - ``handleSIGHUP``: Close the browser process on SIGHUP. Defaults to True. + - ``handleSIGINT``: Close the browser process on Ctrl-C. Defaults to True. + - ``handleSIGTERM``: Close the browser process on SIGTERM. Defaults to True. + - ``ignoreDefaultArgs``: If True, Playwright does not pass its own + configuration args and only uses the ones from ``args``. If a list is + given, then the given default arguments are filtered out. Dangerous + option; use with care. Defaults to None, which means Playwright's own + default arguments are used. + - ``proxy``: Network [#type-Proxy | Proxy] settings. Structure: ``{'server': + , 'bypass': , 'username': , + 'password': }``. Robot Framework 7.4 Secret type is + supported.` + - ``reuse_existing``: If set to True, an existing browser instance that was + created with the same arguments is reused. If no such browser exists, a + new one is started. Defaults to True. + - ``slowMo``: Slows down Playwright operations by the given time, in Robot + Framework time format. Useful so that you can see what is going on. + Defaults to no delay. + - ``timeout``: Maximum time in Robot Framework time format to wait for the + browser instance to start. Defaults to 30 seconds. Pass 0 to disable + timeout. [https://forum.robotframework.org/t//4306|Comment >>] @@ -534,9 +587,11 @@ def launch_browser_server( Returns a websocket endpoint (wsEndpoint) string that can be used to connect to the server. - | =Arguments= | =Description= | - | ``port`` | Port to use for the browser server. Defaults to 0, which results in a random free port being assigned. | - | ``wsPath`` | Path at which to serve the browser server. For security, this defaults to an unguessable string. | + *Arguments:* + - ``port``: Port to use for the browser server. Defaults to 0, which results + in a random free port being assigned. + - ``wsPath``: Path at which to serve the browser server. For security, this + defaults to an unguessable string. Check `New Browser` for the other argument docs. @@ -564,8 +619,10 @@ def close_browser_server(self, wsEndpoint: str) -> None: The wsEndpoint string is returned by `Launch Browser Server` and is also used by `Connect To Browser`. - | =Arguments= | =Description= | - | ``wsEndpoint`` | Address of the browser server. Example: ``ws://127.0.0.1:63784/ca69bf0e9471391e8183d9ac1e90e1ba``| + *Arguments:* + - ``wsEndpoint``: Address of the browser server. Example: + ``ws://127.0.0.1:63784/ca69bf0e9471391e8183d9ac1e90e1ba`` + """ with self.playwright.grpc_channel() as stub: response = stub.CloseBrowserServer(Request().ConnectBrowser(url=wsEndpoint)) @@ -636,37 +693,104 @@ def new_context( Returns a stable identifier for the created context that can be used in `Switch Context`. - - | =Arguments= | =Description= | - | ``acceptDownloads`` | Whether to automatically download all the attachments. Defaults to True where all the downloads are accepted. | - | ``baseURL`` | When using `Go To`, `Wait For Request`, `Wait For Response` or `Wait For Navigation` it takes the base URL in consideration by using the URL() constructor for building the corresponding URL. Unset by default. Examples: ``baseURL=http://localhost:3000`` and navigating to ``/bar.html`` results in ``http://localhost:3000/bar.html``. ``baseURL=http://localhost:3000/foo/`` and navigating to ``./bar.html`` results in ``http://localhost:3000/foo/bar.html``. ``baseURL=http://localhost:3000/foo`` (without trailing slash) and navigating to ``./bar.html`` results in ``http://localhost:3000/bar.html``. | - | ``bypassCSP`` | Toggles bypassing page's Content-Security-Policy. Defaults to False. | - | ``clientCertificates`` | Specifies a client certificate for mTLS authentication, for example ``clientCertificates=[{'origin': 'https://playwright.dev', 'pfxPath': 'certificate.p12', 'passphrase': 'password'}]``. *NOTE:* The origin needs to be exact without any path. | - | ``colorScheme`` | Emulates the ``prefers-color-scheme`` media feature, supported values are ``light``, ``dark``, ``no-preference`` and ``null``. ``null`` disables the emulation. | - | ``defaultBrowserType`` | If no browser is open and `New Context` opens a new browser with defaults, this setting defines which browser is opened. Very useful together with the `Get Device` keyword. | - | ``deviceScaleFactor`` | Specify device scale factor (can be thought of as dpr). Defaults to ``1``. | - | ``extraHTTPHeaders`` | A dictionary containing additional HTTP headers to be sent with every request. All header values must be strings. | - | ``forcedColors`` | Emulates the ``forced-colors`` media feature, supported values are ``active``, ``none`` and ``null``. Defaults to ``none``. | - | ``geolocation`` | A dictionary containing ``latitude`` and ``longitude`` and optionally ``accuracy`` to emulate. If ``latitude`` or ``longitude`` is not specified, the device geolocation won't be overridden. | - | ``hasTouch`` | Specifies if viewport supports touch events. Defaults to False. | - | ``httpCredentials`` | Credentials for [https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication|HTTP authentication]. | - | ``ignoreHTTPSErrors`` | Whether to ignore HTTPS errors during navigation. Defaults to False. | - | ``isMobile`` | Whether the meta viewport tag is taken into account and touch events are enabled. Defaults to False. | - | ``javaScriptEnabled`` | Whether or not to enable JavaScript in the context. Defaults to True. | - | ``locale`` | Specify user locale, for example ``en-GB``, ``de-DE``, etc. | - | ``offline`` | Toggles browser's offline mode. Defaults to False. | - | ``permissions`` | A list containing permissions to grant to all pages in this context. All permissions that are not listed here will be automatically denied. | - | ``proxy`` | Network proxy settings to use with this context. Defaults to None. *NOTE:* For Chromium on Windows the browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example ``proxy={ server: 'http://per-context' }``. | - | ``recordHar`` | Enables [http://www.softwareishard.com/blog/har-12-spec/|HAR] recording for all pages into a file. The ``path`` key must be a path to a file, for example ``recordHar={'path': '${OUTPUT_DIR}/har.file'}``. If not specified, the HAR is not recorded. Make sure to close the context for the HAR to be saved. | - | ``recordVideo`` | Enables video recording for all pages into a folder. If not specified videos are not recorded. Make sure to close the context for videos to be saved. Video is not supported in remote browsers. | - | ``reducedMotion`` | Emulates the ``prefers-reduced-motion`` media feature, supported values are ``reduce`` and ``no-preference``. Defaults to ``no-preference``. | - | ``screen`` | Emulates consistent window screen size available inside web page via window.screen. Is only used when the viewport is set. Example {'width': 414, 'height': 896} | - | ``serviceWorkers`` | Whether to allow sites to register Service workers. Defaults to ``allow``. | - | ``storageState`` | Restores the storage state created by the `Save Storage State` keyword. Must be a path to an existing file, otherwise the keyword fails. Relative paths are resolved against the current working directory. | - | ``timezoneId`` | Changes the timezone of the context. See [https://source.chromium.org/chromium/chromium/src/+/master:third_party/icu/source/data/misc/metaZones.txt|ICU`s metaZones.txt] for a list of supported timezone IDs. | - | ``tracing`` | Boolean ``True`` (recommendation) or file path or directory where the [https://playwright.dev/docs/api/class-tracing/|tracing] file is saved. The string ``{contextid}`` will be replaced with the context id. Path to *.zip files can be absolute or relative to ${OUTPUT_DIR}. Path to folders can be absolute or relative to ${OUTPUT_DIR}/browser/traces. If boolean ``True`` or a directory is given, the trace file will automatically be named ``trace_{contextid}.zip``. Temporary trace files will be saved to ${OUTPUT_DIR}/browser/traces/temp. Tracing is automatically closed when context is closed. Temporary trace files will be automatically deleted at start of each test execution. Trace file can be opened after the test execution by running command from shell: ``rfbrowser show-trace /path/to/trace.zip``. Tracing can also be enabled by setting a Robot Framework variable or environment variable ``ROBOT_FRAMEWORK_BROWSER_TRACING`` to ``True``. | - | ``userAgent`` | Specific user agent to use in this context. | - | ``viewport`` | A dictionary containing ``width`` and ``height``. Emulates consistent viewport for each page. Defaults to 1280x720. ``None`` disables the default viewport. If ``width`` and ``height`` are ``0``, the viewport will scale with the window. | + *Arguments:* + - ``acceptDownloads``: Whether to automatically download all the attachments. + Defaults to True where all the downloads are accepted. + - ``baseURL``: When using `Go To`, `Wait For Request`, `Wait For Response` or + `Wait For Navigation` it takes the base URL in consideration by using + the URL() constructor for building the corresponding URL. Unset by + default. Examples: ``baseURL=http://localhost:3000`` and navigating to + ``/bar.html`` results in ``http://localhost:3000/bar.html``. + ``baseURL=http://localhost:3000/foo/`` and navigating to ``./bar.html`` + results in ``http://localhost:3000/foo/bar.html``. + ``baseURL=http://localhost:3000/foo`` (without trailing slash) and + navigating to ``./bar.html`` results in + ``http://localhost:3000/bar.html``. + - ``bypassCSP``: Toggles bypassing page's Content-Security-Policy. Defaults to + False. + - ``clientCertificates``: Specifies a client certificate for mTLS + authentication, for example ``clientCertificates=[{'origin': + 'https://playwright.dev', 'pfxPath': 'certificate.p12', 'passphrase': + 'password'}]``. *NOTE:* The origin needs to be exact without any path. + - ``colorScheme``: Emulates the ``prefers-color-scheme`` media feature, + supported values are ``light``, ``dark``, ``no-preference`` and + ``null``. ``null`` disables the emulation. + - ``defaultBrowserType``: If no browser is open and `New Context` opens a new + browser with defaults, this setting defines which browser is opened. + Very useful together with the `Get Device` keyword. + - ``deviceScaleFactor``: Specify device scale factor (can be thought of as + dpr). Defaults to ``1``. + - ``extraHTTPHeaders``: A dictionary containing additional HTTP headers to be + sent with every request. All header values must be strings. + - ``forcedColors``: Emulates the ``forced-colors`` media feature, supported + values are ``active``, ``none`` and ``null``. Defaults to ``none``. + - ``geolocation``: A dictionary containing ``latitude`` and ``longitude`` and + optionally ``accuracy`` to emulate. If ``latitude`` or ``longitude`` is + not specified, the device geolocation won't be overridden. + - ``hasTouch``: Specifies if viewport supports touch events. Defaults to + False. + - ``httpCredentials``: Credentials for + [https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication | HTTP + authentication]. + - ``ignoreHTTPSErrors``: Whether to ignore HTTPS errors during navigation. + Defaults to False. + - ``isMobile``: Whether the meta viewport tag is taken into account and touch + events are enabled. Defaults to False. + - ``javaScriptEnabled``: Whether or not to enable JavaScript in the context. + Defaults to True. + - ``locale``: Specify user locale, for example ``en-GB``, ``de-DE``, etc. + - ``offline``: Toggles browser's offline mode. Defaults to False. + - ``permissions``: A list containing permissions to grant to all pages in this + context. All permissions that are not listed here will be automatically + denied. + - ``proxy``: Network proxy settings to use with this context. Defaults to + None. *NOTE:* For Chromium on Windows the browser needs to be launched + with the global proxy for this option to work. If all contexts override + the proxy, global proxy will be never used and can be any string, for + example ``proxy={ server: 'http://per-context' }``. + - ``recordHar``: Enables [http://www.softwareishard.com/blog/har-12-spec/ | + HAR] recording for all pages into a file. The ``path`` key must be a + path to a file, for example ``recordHar={'path': + '${OUTPUT_DIR}/har.file'}``. If not specified, the HAR is not recorded. + Make sure to close the context for the HAR to be saved. + - ``recordVideo``: Enables video recording for all pages into a folder. If not + specified videos are not recorded. Make sure to close the context for + videos to be saved. Video is not supported in remote browsers. + - ``reducedMotion``: Emulates the ``prefers-reduced-motion`` media feature, + supported values are ``reduce`` and ``no-preference``. Defaults to + ``no-preference``. + - ``screen``: Emulates consistent window screen size available inside web page + via window.screen. Is only used when the viewport is set. Example + {'width': 414, 'height': 896} + - ``serviceWorkers``: Whether to allow sites to register Service workers. + Defaults to ``allow``. + - ``storageState``: Restores the storage state created by the `Save Storage + State` keyword. Must be a path to an existing file, otherwise the + keyword fails. Relative paths are resolved against the current working + directory. + - ``timezoneId``: Changes the timezone of the context. See + [https://source.chromium.org/chromium/chromium/src/+/master:third_party/icu/source/data/misc/metaZones.txt | ICU metaZones.txt] + for a list of supported timezone IDs. + - ``tracing``: Boolean ``True`` (recommendation) or file path or directory + where the [https://playwright.dev/docs/api/class-tracing/ | tracing] + file is saved. The string ``{contextid}`` will be replaced with the + context id. Path to *.zip files can be absolute or relative to + ${OUTPUT_DIR}. Path to folders can be absolute or relative to + ${OUTPUT_DIR}/browser/traces. If boolean ``True`` or a directory is + given, the trace file will automatically be named + ``trace_{contextid}.zip``. Temporary trace files will be saved to + ${OUTPUT_DIR}/browser/traces/temp. Tracing is automatically closed when + context is closed. Temporary trace files will be automatically deleted + at start of each test execution. Trace file can be opened after the test + execution by running command from shell: ``rfbrowser show-trace + /path/to/trace.zip``. Tracing can also be enabled by setting a Robot + Framework variable or environment variable + ``ROBOT_FRAMEWORK_BROWSER_TRACING`` to ``True``. + - ``userAgent``: Specific user agent to use in this context. + - ``viewport``: A dictionary containing ``width`` and ``height``. Emulates + consistent viewport for each page. Defaults to 1280x720. ``None`` + disables the default viewport. If ``width`` and ``height`` are ``0``, + the viewport will scale with the window. Example: @@ -782,11 +906,18 @@ def new_persistent_context( This keyword returns a tuple of browser id, context id and page details. (New in Browser 15.0.0) - | =Argument= | =Description= | - | ``userDataDir`` | Path to a User Data Directory, which stores browser session data like cookies and local storage. Note that Chromium's user data directory is the parent directory of the "Profile Path" seen at chrome://version. Pass an empty string to use a temporary directory instead. | - | ``browser`` | Browser type to use. Default is Chromium. | - | ``headless`` | Whether to run browser in headless mode. Defaults to ``True``. | - | other arguments | Please see `New Browser`, `New Context` and `New Page` for more information about the other arguments. | + *Arguments:* + - ``userDataDir``: Path to a User Data Directory, which stores browser session + data like cookies and local storage. Note that Chromium's user data + directory is the parent directory of the "Profile Path" seen at + chrome://version. Pass an empty string to use a temporary directory + instead. + - ``browser``: Browser type to use. Default is Chromium. + - ``headless``: Whether to run browser in headless mode. Defaults to ``True``. + + + ``other Arguments``: Please see `New Browser`, `New Context` and `New Page` for more + information about the other arguments. If you want to use extensions you need to download the extension as a .zip, enable loading the extension, and load the extensions using chromium arguments like below. Extensions only work with chromium and with a headful browser. @@ -1007,9 +1138,16 @@ def new_page( A Page is the Playwright equivalent to a tab. See `Browser, Context and Page` for more information about Page concept. - | =Arguments= | =Description= | - | ``url`` | Optional URL to navigate the page to. The url should include the protocol, for example ``https://``. | - | ``wait_until`` | When to consider operation succeeded, defaults to load. Events can be either: ``domcontentloaded`` - consider operation to be finished when the DOMContentLoaded event is fired. ``load`` - consider operation to be finished when the load event is fired. ``networkidle`` - consider operation to be finished when there are no network connections for at least 500 ms. ``commit`` - consider operation to be finished when network response is received and the document started loading. | + *Arguments:* + - ``url``: Optional URL to navigate the page to. The url should include the + protocol, for example ``https://``. + - ``wait_until``: When to consider operation succeeded, defaults to load. + Events can be either: ``domcontentloaded`` - consider operation to be + finished when the DOMContentLoaded event is fired. ``load`` - consider + operation to be finished when the load event is fired. ``networkidle`` - + consider operation to be finished when there are no network connections + for at least 500 ms. ``commit`` - consider operation to be finished when + network response is received and the document started loading. Returns `NewPageDetails` as dictionary for created page. @@ -1082,10 +1220,13 @@ def get_browser_catalog( See `Browser, Context and Page` for more information about these concepts. - | =Arguments= | =Description= | - | assertion_operator | Optional assertion operator. See `Assertions` for more information. | - | assertion_expected | Optional expected value. See `Assertions` for more information. | - | message | Optional custom message to use on failure. See `Assertions` for more information. | + *Arguments:* + - ``assertion_operator``: Optional assertion operator. See `Assertions` for + more information. + - ``assertion_expected``: Optional expected value. See `Assertions` for more + information. + - ``message``: Optional custom message to use on failure. See `Assertions` for + more information. The data is parsed into a python list containing data representing the open Objects. @@ -1187,12 +1328,17 @@ def get_console_log( If assertions are used and fail, this keyword will fail immediately without retrying. - | =Arguments= | =Description= | - | assertion_operator | Optional assertion operator. See `Assertions` for more information. | - | assertion_expected | Optional expected value. See `Assertions` for more information. | - | message | Optional custom message to use on failure. See `Assertions` for more information. | - | full | If true, returns the full console log. If false, returns only new entries that were added since last time. | - | last | If set, returns only the last n entries. Can be an integer for the number of entries or a time period in Robot Framework time format. | + *Arguments:* + - ``assertion_operator``: Optional assertion operator. See `Assertions` for + more information. + - ``assertion_expected``: Optional expected value. See `Assertions` for more + information. + - ``message``: Optional custom message to use on failure. See `Assertions` for + more information. + - ``full``: If true, returns the full console log. If false, returns only new + entries that were added since last time. + - ``last``: If set, returns only the last n entries. Can be an integer for the + number of entries or a time period in Robot Framework time format. The returned data is a list of log messages. @@ -1259,12 +1405,17 @@ def get_page_errors( If assertions are used and fail, this keyword will fail immediately without retrying. - | =Arguments= | =Description= | - | assertion_operator | Optional assertion operator. See `Assertions` for more information. | - | assertion_expected | Optional expected value. See `Assertions` for more information. | - | message | Optional custom message to use on failure. See `Assertions` for more information. | - | full | If true, returns all page errors. If false, returns only new errors that were added since last time. | - | last | If set, returns only the last n entries. Can be an integer for the number of entries or a time period in Robot Framework time format. | + *Arguments:* + - ``assertion_operator``: Optional assertion operator. See `Assertions` for + more information. + - ``assertion_expected``: Optional expected value. See `Assertions` for more + information. + - ``message``: Optional custom message to use on failure. See `Assertions` for + more information. + - ``full``: If true, returns all page errors. If false, returns only new + errors that were added since last time. + - ``last``: If set, returns only the last n entries. Can be an integer for the + number of entries or a time period in Robot Framework time format. The returned data is a list of error messages. @@ -1328,8 +1479,11 @@ def switch_browser(self, id: str) -> str: # noqa: A002 Returns a stable identifier for the previous browser. See `Browser, Context and Page` for more information about Browser and related concepts. - | =Arguments= | =Description= | - | id | The id of the browser to switch to. Example: ``browser=96207191-8147-44e7-b9ac-5e04f2709c1d``. A browser id is returned by `New Browser` when it is started or can be fetched from the browser catalog when returned by `Get Browser Catalog`. | + *Arguments:* + - ``id``: The id of the browser to switch to. Example: + ``browser=96207191-8147-44e7-b9ac-5e04f2709c1d``. A browser id is + returned by `New Browser` when it is started or can be fetched from the + browser catalog when returned by `Get Browser Catalog`. [https://forum.robotframework.org/t//4334|Comment >>] """ @@ -1365,9 +1519,14 @@ def switch_context( Returns a stable identifier for the previous context. See `Browser, Context and Page` for more information about Context and related concepts. - | =Arguments= | =Description= | - | ``id`` | The id of the context to switch to. Example: ``context=525d8e5b-3c4e-4baa-bfd4-dfdbc6e86089``. A context id is returned by `New Context` when it is started or can be fetched from the browser catalog when returned by `Get Browser Catalog`. | - | ``browser`` | The browser in which to search for that context. ``CURRENT`` for the currently active browser, ``ALL`` to search in all open browsers or the id of the browser where to switch context. | + *Arguments:* + - ``id``: The id of the context to switch to. Example: + ``context=525d8e5b-3c4e-4baa-bfd4-dfdbc6e86089``. A context id is + returned by `New Context` when it is started or can be fetched from the + browser catalog when returned by `Get Browser Catalog`. + - ``browser``: The browser in which to search for that context. ``CURRENT`` + for the currently active browser, ``ALL`` to search in all open browsers + or the id of the browser where to switch context. Example: | ${first_context} = `New Context` @@ -1419,10 +1578,20 @@ def switch_page( Returns a stable identifier ``id`` for the previous page. See `Browser, Context and Page` for more information about Page and related concepts. - | =Arguments= | =Description= | - | ``id`` | The id or alias of the page to switch to. Example: ``page=8baf2991-5eaf-444d-a318-8045f914e96a`` or ``NEW``. Can be a string or a dictionary returned by `New Page` Keyword. A page id can be fetched from the browser catalog when returned by `Get Browser Catalog`. ``NEW`` can be used to switch to a pop-up that just has been opened by the webpage, ``CURRENT`` can be used to switch to the active page of a different context or browser, identified by their id. | - | ``context`` | The context in which to search for that page. ``CURRENT`` for the currently active context, ``ALL`` to search in all open contexts or the id of the context where to switch page. | - | ``browser`` | The browser in which to search for that page. ``CURRENT`` for the currently active browser, ``ALL`` to search in all open browsers or the id of the browser where to switch page. | + *Arguments:* + - ``id``: The id or alias of the page to switch to. Example: + ``page=8baf2991-5eaf-444d-a318-8045f914e96a`` or ``NEW``. Can be a + string or a dictionary returned by `New Page` Keyword. A page id can be + fetched from the browser catalog when returned by `Get Browser Catalog`. + ``NEW`` can be used to switch to a pop-up that just has been opened by + the webpage, ``CURRENT`` can be used to switch to the active page of a + different context or browser, identified by their id. + - ``context``: The context in which to search for that page. ``CURRENT`` for + the currently active context, ``ALL`` to search in all open contexts or + the id of the context where to switch page. + - ``browser``: The browser in which to search for that page. ``CURRENT`` for + the currently active browser, ``ALL`` to search in all open browsers or + the id of the browser where to switch page. If a page id is given, the ``context`` and ``browser`` arguments are ignored and the page is searched from all open browsers. @@ -1525,8 +1694,9 @@ def get_browser_ids( - ``ALL`` / ``ANY`` Returns all ids as a list. - ``ACTIVE`` / ``CURRENT`` Returns the id of the currently active browser as list. - | =Arguments= | =Description= | - | ``browser`` | The browser to get the ids from. ``ALL`` for all open browsers or ``ACTIVE`` for the currently active browser. | + *Arguments:* + - ``browser``: The browser to get the ids from. ``ALL`` for all open browsers + or ``ACTIVE`` for the currently active browser. The ACTIVE browser is a synonym for the CURRENT Browser. @@ -1556,9 +1726,14 @@ def get_context_ids( ``ALL`` and ``ANY`` are synonyms. ``ACTIVE`` and ``CURRENT`` are also synonyms. - | =Arguments= | =Description= | - | ``context`` | The context to get the ids from. ``ALL`` will return all ids from selected browser(s), ``ACTIVE`` for the one active context of each selected browser. | - | ``browser`` | The browser id or selection to get the context ids from. ``ALL`` Context ids from all open browsers shall be fetched. ``ACTIVE`` Only context ids from the active browser shall be fetched. If a browser id is given and no browser with that id is open, the keyword fails. | + *Arguments:* + - ``context``: The context to get the ids from. ``ALL`` will return all ids + from selected browser(s), ``ACTIVE`` for the one active context of each + selected browser. + - ``browser``: The browser id or selection to get the context ids from. + ``ALL`` Context ids from all open browsers shall be fetched. ``ACTIVE`` + Only context ids from the active browser shall be fetched. If a browser + id is given and no browser with that id is open, the keyword fails. The ACTIVE context of the ACTIVE Browser is the ``Current`` Context. @@ -1641,10 +1816,15 @@ def get_page_ids( ``ALL`` and ``ANY`` are synonyms. ``ACTIVE`` and ``CURRENT`` are also synonyms. - | =Arguments= | =Description= | - | ``page`` | The page to get the ids from. ``ALL`` Returns all page ids as a list. ``ACTIVE`` Returns the id of the active page as a list. | - | ``context`` | The context id or selection to get the page ids from. ``ALL`` Page ids from all contexts shall be fetched. ``ACTIVE`` Only page ids from the active context shall be fetched. | - | ``browser`` | The browser id or selection to get the page ids from. ``ALL`` Page ids from all open browsers shall be fetched. ``ACTIVE`` Only page ids from the active browser shall be fetched. | + *Arguments:* + - ``page``: The page to get the ids from. ``ALL`` Returns all page ids as a + list. ``ACTIVE`` Returns the id of the active page as a list. + - ``context``: The context id or selection to get the page ids from. ``ALL`` + Page ids from all contexts shall be fetched. ``ACTIVE`` Only page ids + from the active context shall be fetched. + - ``browser``: The browser id or selection to get the page ids from. ``ALL`` + Page ids from all open browsers shall be fetched. ``ACTIVE`` Only page + ids from the active browser shall be fetched. Example: @@ -1716,10 +1896,18 @@ def save_storage_state( Please note that the state file may contain secrets and should not be shared with people outside of your organisation. - | =Arguments= | =Description= | - | ``path`` | Where the state file is written. Relative paths are resolved against the current working directory and missing parent directories are created. If the file already exists, it is overwritten. If not given, a file with a generated name is created in ${OUTPUTDIR}/browser/state. The absolute path of the written file is returned. | - | ``indexedDB`` | Also save IndexedDB. Needed by applications, like Firebase, which store authentication tokens in IndexedDB. | - | ``credentials`` | Also save the context's virtual WebAuthn credentials, as created by `Create Credential`. This is not related to the ``httpCredentials`` argument of `New Context`, which is about HTTP authentication. | + *Arguments:* + - ``path``: Where the state file is written. Relative paths are resolved + against the current working directory and missing parent directories are + created. If the file already exists, it is overwritten. If not given, a + file with a generated name is created in ${OUTPUTDIR}/browser/state. The + absolute path of the written file is returned. + - ``indexedDB``: Also save IndexedDB. Needed by applications, like Firebase, + which store authentication tokens in IndexedDB. + - ``credentials``: Also save the context's virtual WebAuthn credentials, as + created by `Create Credential`. This is not related to the + ``httpCredentials`` argument of `New Context`, which is about HTTP + authentication. Files in ${OUTPUTDIR}/browser/state are automatically deleted when new test execution starts. To keep a state file over several executions, @@ -1798,10 +1986,14 @@ def set_storage_state( `Install Credential` does. Real authenticators do not work in that context afterwards. - | =Arguments= | =Description= | - | ``path`` | Path to a state file created by `Save Storage State`. Relative paths are resolved against the current working directory. The keyword fails if the file does not exist. | - | ``timeout`` | Time to wait for the state to be restored. If not defined, the library default timeout is used. Pass 0 to disable the timeout. | - | ``reload_pages`` | Which pages are reloaded while the state is restored, see `ReloadPages`. Only relevant when the state file contains IndexedDB. | + *Arguments:* + - ``path``: Path to a state file created by `Save Storage State`. Relative + paths are resolved against the current working directory. The keyword + fails if the file does not exist. + - ``timeout``: Time to wait for the state to be restored. If not defined, the + library default timeout is used. Pass 0 to disable the timeout. + - ``reload_pages``: Which pages are reloaded while the state is restored, see + `ReloadPages`. Only relevant when the state file contains IndexedDB. == Restoring IndexedDB == @@ -1871,8 +2063,8 @@ def set_peer_id(self, new_id) -> str: def cancel_download(self, download: DownloadInfo | str): """Cancels an active download. - | =Arguments= | =Description= | - | download | A `DownloadInfo` object or id of the download to be canceled. | + *Arguments:* + - ``download``: A `DownloadInfo` object or id of the download to be canceled. [https://forum.robotframework.org/t//6478|Comment >>] """ diff --git a/Browser/keywords/promises.py b/Browser/keywords/promises.py index 42d24d770..cc4f7aba2 100644 --- a/Browser/keywords/promises.py +++ b/Browser/keywords/promises.py @@ -50,9 +50,9 @@ def promise_to(self, kw: str, *args) -> Future: Only Browser library keywords can be promised, any other keyword name fails the keyword. - | =Arguments= | =Description= | - | ``kw`` | Keyword that will run asynchronously in the background. | - | ``*args`` | Keyword arguments as normally used. | + *Arguments:* + - ``kw``: Keyword that will run asynchronously in the background. + - ``*args``: Keyword arguments as normally used. Example: | ${promise}= `Promise To` Wait For Response matcher= timeout=3 @@ -155,10 +155,20 @@ def promise_to_wait_for_download( If browser is connected remotely with `Connect To Browser` then ``saveAs`` must be set to store it locally where the browser runs! - | =Arguments= | =Description= | - | ``saveAs`` | Defines path where the file is saved persistently. File will also temporarily be saved in playwright context's default download location. If empty, generated unique path (GUID) is used and file is deleted when the context is closed. | - | ``wait_for_finished`` | If true, promise will wait for download to finish. If false, promise will resolve immediately after download has started. | - | ``download_timeout`` | Maximum total time for the download to start and finish, counted from the moment the promise is created. If the download does not start within this time, the keyword fails. If it starts but does not finish, it is cancelled and the keyword fails. If ``wait_for_finished`` is ``False``, only the start is limited. If not set, the download must start within the browser timeout, see `Set Browser Timeout`, and there is no limit for it to finish. | + *Arguments:* + - ``saveAs``: Defines path where the file is saved persistently. File will + also temporarily be saved in playwright context's default download + location. If empty, generated unique path (GUID) is used and file is + deleted when the context is closed. + - ``wait_for_finished``: If true, promise will wait for download to finish. If + false, promise will resolve immediately after download has started. + - ``download_timeout``: Maximum total time for the download to start and + finish, counted from the moment the promise is created. If the download + does not start within this time, the keyword fails. If it starts but + does not finish, it is cancelled and the keyword fails. If + ``wait_for_finished`` is ``False``, only the start is limited. If not + set, the download must start within the browser timeout, see `Set + Browser Timeout`, and there is no limit for it to finish. Keyword returns dictionary of type `DownloadInfo` which contains downloaded file path and suggested filename as well as state and downloadID. @@ -248,8 +258,8 @@ def wait_for(self, *promises: Future): For general waiting of elements please see `Implicit waiting`. - | =Arguments= | =Description= | - | ``promises`` | Promises to wait for. | + *Arguments:* + - ``promises``: Promises to wait for. Example: | ${promise}= `Promise To` `Wait For Response` matcher= timeout=3 @@ -288,8 +298,8 @@ def promise_to_upload_file(self, path: PathLike) -> Future: The keyword fails immediately if ``path`` does not point to an existing file. The promise fails if no file chooser dialog is opened within the timeout. - | =Arguments= | =Description= | - | ``path`` | Path to file to be uploaded. | + *Arguments:* + - ``path``: Path to file to be uploaded. Example use: diff --git a/Browser/keywords/runonfailure.py b/Browser/keywords/runonfailure.py index b185d52e1..60a9899c4 100644 --- a/Browser/keywords/runonfailure.py +++ b/Browser/keywords/runonfailure.py @@ -31,10 +31,14 @@ def register_keyword_to_run_on_failure( ) -> DelayedKeyword: """Sets the keyword to execute, when a Browser keyword fails. - | =Arguments= | =Description= | - | ``keyword`` | The name of a keyword that will be executed if a Browser keyword fails. It is possible to use any available keyword, including user keywords or keywords from other libraries. | - | ``*args`` | The arguments to the keyword if any. | - | ``scope`` | Scope defines the lifetime of this setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope Setting` for more details. | + *Arguments:* + - ``keyword``: The name of a keyword that will be executed if a Browser + keyword fails. It is possible to use any available keyword, including + user keywords or keywords from other libraries. + - ``*args``: The arguments to the keyword if any. + - ``scope``: Scope defines the lifetime of this setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope Setting` for + more details. The initial keyword to use is set when `importing` the library, and the keyword that is used by default is diff --git a/Browser/keywords/strict_mode.py b/Browser/keywords/strict_mode.py index c641308ea..dab21c49f 100644 --- a/Browser/keywords/strict_mode.py +++ b/Browser/keywords/strict_mode.py @@ -20,9 +20,16 @@ class StrictMode(LibraryComponent): def set_strict_mode(self, mode: bool, scope: Scope = Scope.Suite): """Controls library strict mode. - | =Arguments= | =Description= | - | ``mode`` | When set to ``True``, keywords that search elements will use Playwright [https://playwright.dev/docs/api/class-page#page-query-selector|strict mode] and fail if the selector matches more than one element. When set to ``False``, such keywords do not fail but operate on the first matching element. | - | ``scope`` | Scope defines the live time of that setting. Available values are ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more details. | + *Arguments:* + - ``mode``: When set to ``True``, keywords that search elements will use + Playwright + [https://playwright.dev/docs/api/class-page#page-query-selector | strict + mode] and fail if the selector matches more than one element. When set + to ``False``, such keywords do not fail but operate on the first + matching element. + - ``scope``: Scope defines the live time of that setting. Available values are + ``Global``, ``Suite`` or ``Test`` / ``Task``. See `Scope` for more + details. The keyword returns the strict mode value which was in use before this keyword was called. diff --git a/Browser/keywords/waiter.py b/Browser/keywords/waiter.py index eaddceee7..4dc7a3cc4 100644 --- a/Browser/keywords/waiter.py +++ b/Browser/keywords/waiter.py @@ -62,11 +62,19 @@ def wait_for_elements_state( If the selector doesn't satisfy the condition within the timeout the keyword will FAIL. - | =Arguments= | =Description= | - | ``selector`` | Selector of the corresponding object. See the `Finding elements` section for details about the selectors. | - | ``state`` | See `ElementState` for explanation. | - | ``timeout`` | uses default timeout from library if not set. | - | ``message`` | overrides the default error message. The ``message`` argument accepts `{selector}`, ``{function}``, and `{timeout}` [https://docs.python.org/3/library/stdtypes.html#str.format|format] options. The ``{function}`` formatter is the ``state`` argument value for the states which are waited for by Playwright, that are ``attached``, ``detached``, ``visible``, ``hidden``, ``stable``, ``enabled``, ``disabled`` and ``editable``. For all other states, it is the JavaScript expression which is evaluated for the element. | + *Arguments:* + - ``selector``: Selector of the corresponding object. See the `Finding + elements` section for details about the selectors. + - ``state``: See `ElementState` for explanation. + - ``timeout``: uses default timeout from library if not set. + - ``message``: overrides the default error message. The ``message`` argument + accepts `{selector}`, ``{function}``, and `{timeout}` + [https://docs.python.org/3/library/stdtypes.html#str.format | format] + options. The ``{function}`` formatter is the ``state`` argument value + for the states which are waited for by Playwright, that are + ``attached``, ``detached``, ``visible``, ``hidden``, ``stable``, + ``enabled``, ``disabled`` and ``editable``. For all other states, it is + the JavaScript expression which is evaluated for the element. The states ``focused`` and ``defocused`` are not supported with iframe selectors, which contain ``>>>``. In that case the keyword raises an error and suggests to use @@ -174,12 +182,23 @@ def wait_for_function( ): """Polls JavaScript expression or function in browser until it returns a (JavaScript) truthy value. - | =Arguments= | =Description= | - | ``function`` | A valid javascript function or a javascript function body. For example ``() => true`` and ``true`` will behave similarly. | - | ``selector`` | Selector to resolve and pass to the JavaScript function. This will be the first argument the function receives. If a selector is given, ``function`` must be a function with an argument which receives the element handle. For example ``(element) => document.activeElement === element``. See the `Finding elements` section for details about the selectors. | - | ``polling`` | Default polling value of ``raf`` polls in a callback for ``requestAnimationFrame``. Any other value for polling will be parsed as a Robot Framework time for the interval between polls. | - | ``timeout`` | Uses default timeout of the library if not set. | - | ``message`` | overrides the default error message. The ``message`` argument accepts `{selector}`, ``{function}``, and `{timeout}` [https://docs.python.org/3/library/stdtypes.html#str.format|format] options. | + *Arguments:* + - ``function``: A valid javascript function or a javascript function body. For + example ``() => true`` and ``true`` will behave similarly. + - ``selector``: Selector to resolve and pass to the JavaScript function. This + will be the first argument the function receives. If a selector is + given, ``function`` must be a function with an argument which receives + the element handle. For example ``(element) => document.activeElement + === element``. See the `Finding elements` section for details about the + selectors. + - ``polling``: Default polling value of ``raf`` polls in a callback for + ``requestAnimationFrame``. Any other value for polling will be parsed as + a Robot Framework time for the interval between polls. + - ``timeout``: Uses default timeout of the library if not set. + - ``message``: overrides the default error message. The ``message`` argument + accepts `{selector}`, ``{function}``, and `{timeout}` + [https://docs.python.org/3/library/stdtypes.html#str.format | format] + options. Keyword uses strict mode, see `Finding elements` for more details about strict mode. @@ -255,11 +274,15 @@ def wait_for_condition( In comparison to Robot Framework's ``Wait Until Keyword Succeeds`` this keyword is more readable and easier to use, but is limited to Browser library's assertion keywords. - | =Arguments= | =Description= | - | ``condition`` | A condition, defined with Browser getter keywords, without the word ``Get``. | - | ``*args`` | Arguments to pass to the condition keyword. | - | ``timeout`` | Timeout to wait for the condition to become True. Uses default timeout of the library if not set. As the other assertion keywords this timeout only influences the time the assertion is retried. The browser timeout is used to wait for the element to be found. | - | ``message`` | Overrides the default error message. | + *Arguments:* + - ``condition``: A condition, defined with Browser getter keywords, without + the word ``Get``. + - ``*args``: Arguments to pass to the condition keyword. + - ``timeout``: Timeout to wait for the condition to become True. Uses default + timeout of the library if not set. As the other assertion keywords this + timeout only influences the time the assertion is retried. The browser + timeout is used to wait for the element to be found. + - ``message``: Overrides the default error message. The easiest way to use this keyword is first starting with an assertion keyword with assertion like: `Get Text` @@ -320,9 +343,11 @@ def wait_for_load_state( The navigation must have been committed when this method is called. If current document has already reached the required state, resolves immediately. - | =Arguments= | =Description= | - | ``state`` | State to wait for, defaults to ``load``. Possible values are ``load``, ``domcontentloaded``, ``networkidle`` and ``commit``. | - | ``timeout`` | Timeout supports Robot Framework time format. Uses browser timeout if not set. | + *Arguments:* + - ``state``: State to wait for, defaults to ``load``. Possible values are + ``load``, ``domcontentloaded``, ``networkidle`` and ``commit``. + - ``timeout``: Timeout supports Robot Framework time format. Uses browser + timeout if not set. If the state has been already reached while loading current document, the underlying Playwright will resolve immediately. Can be one of: diff --git a/Browser/keywords/webapp_state.py b/Browser/keywords/webapp_state.py index fd93e80ac..b9c42b8be 100644 --- a/Browser/keywords/webapp_state.py +++ b/Browser/keywords/webapp_state.py @@ -49,12 +49,15 @@ def local_storage_get_item( ) -> Any: """Get saved data from the local storage. - | =Arguments= | =Description= | - | ``key`` | Named key of the item in the storage. | - | ``assertion_operator`` | Assertion operator to use. See `Assertions` for more information. | - | ``assertion_expected`` | Expected value to compare with. | - | ``message`` | Custom error message to use. | - | ``frame_selector`` | If this selector points to an element inside an iframe, the LocalStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``key``: Named key of the item in the storage. + - ``assertion_operator``: Assertion operator to use. See `Assertions` for more + information. + - ``assertion_expected``: Expected value to compare with. + - ``message``: Custom error message to use. + - ``frame_selector``: If this selector points to an element inside an iframe, + the LocalStorage of that frame is used. Example: ``iframe[name="test"] + >>> body`` See `Assertions` for further details about the assertion arguments. They default to ``None``. @@ -87,10 +90,12 @@ def local_storage_set_item( ): """Save data to the local storage. - | =Arguments= | =Description= | - | ``key`` | The name of the key under which it should be saved. | - | ``value`` | The value which shall be saved as a string. | - | ``frame_selector`` | If this selector points to an element inside an iframe, the LocalStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``key``: The name of the key under which it should be saved. + - ``value``: The value which shall be saved as a string. + - ``frame_selector``: If this selector points to an element inside an iframe, + the LocalStorage of that frame is used. Example: ``iframe[name="test"] + >>> body`` Example: @@ -108,9 +113,11 @@ def local_storage_set_item( def local_storage_remove_item(self, key: str, frame_selector: str | None = None): """Remove saved data with key from the local storage. - | =Arguments= | =Description= | - | ``key`` | The name of the item which shall be deleted. | - | ``frame_selector`` | If this selector points to an element inside an iframe, the LocalStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``key``: The name of the item which shall be deleted. + - ``frame_selector``: If this selector points to an element inside an iframe, + the LocalStorage of that frame is used. Example: ``iframe[name="test"] + >>> body`` Example: | `LocalStorage Set Item` Foo bar @@ -129,8 +136,10 @@ def local_storage_remove_item(self, key: str, frame_selector: str | None = None) def local_storage_clear(self, frame_selector: str | None = None): """Remove all saved data from the local storage. - | =Arguments= | =Description= | - | ``frame_selector`` | If this selector points to an element inside an iframe, the LocalStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``frame_selector``: If this selector points to an element inside an iframe, + the LocalStorage of that frame is used. + Example: ``iframe[name="test"] >>> body`` Example: | `LocalStorage Set Item` Foo bar @@ -158,12 +167,15 @@ def session_storage_get_item( ) -> Any: """Get saved data from the session storage. - | =Arguments= | =Description= | - | ``key`` | Named key of the item in the storage. | - | ``assertion_operator`` | Assertion operator to use. See `Assertions` for more information. | - | ``assertion_expected`` | Expected value to compare with. | - | ``message`` | Custom error message to use. | - | ``frame_selector`` | If this selector points to an element inside an iframe, the SessionStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``key``: Named key of the item in the storage. + - ``assertion_operator``: Assertion operator to use. See `Assertions` for more + information. + - ``assertion_expected``: Expected value to compare with. + - ``message``: Custom error message to use. + - ``frame_selector``: If this selector points to an element inside an iframe, + the SessionStorage of that frame is used. Example: ``iframe[name="test"] + >>> body`` See `Assertions` for further details about the assertion arguments. They default to ``None``. @@ -196,10 +208,12 @@ def session_storage_set_item( ): """Save data to session storage. - | =Arguments= | =Description= | - | ``key`` | The name of the key under which it should be saved. | - | ``value`` | The value which shall be saved as a string. | - | ``frame_selector`` | If this selector points to an element inside an iframe, the SessionStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``key``: The name of the key under which it should be saved. + - ``value``: The value which shall be saved as a string. + - ``frame_selector``: If this selector points to an element inside an iframe, + the SessionStorage of that frame is used. Example: ``iframe[name="test"] + >>> body`` Example: | `SessionStorage Set Item` key2 value2 @@ -216,9 +230,11 @@ def session_storage_set_item( def session_storage_remove_item(self, key: str, frame_selector: str | None = None): """Remove saved data with key from the session storage. - | =Arguments= | =Description= | - | ``key`` | The name of the item which shall be deleted. | - | ``frame_selector`` | If this selector points to an element inside an iframe, the SessionStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``key``: The name of the item which shall be deleted. + - ``frame_selector``: If this selector points to an element inside an iframe, + the SessionStorage of that frame is used. Example: ``iframe[name="test"] + >>> body`` Example: | `SessionStorage Set Item` mykey2 myvalue2 @@ -236,8 +252,11 @@ def session_storage_remove_item(self, key: str, frame_selector: str | None = Non def session_storage_clear(self, frame_selector: str | None = None): """Remove all saved data from the session storage. - | =Arguments= | =Description= | - | ``frame_selector`` | If this selector points to an element inside an iframe, the SessionStorage of that frame is used. Example: ``iframe[name="test"] >>> body`` | + *Arguments:* + - ``frame_selector``: If this selector points to an element inside an iframe, + the SessionStorage of that frame is used. + + Example: ``iframe[name="test"] >>> body`` Example: | `SessionStorage Set Item` mykey3 myvalue3 diff --git a/atest/test/12_rfbrowser/translation.robot b/atest/test/12_rfbrowser/translation.robot index 732d7a8d1..61c9c130e 100644 --- a/atest/test/12_rfbrowser/translation.robot +++ b/atest/test/12_rfbrowser/translation.robot @@ -28,7 +28,7 @@ Create Translation File With Python Plugin Should Start With ${inro}[doc] Browser library is a browser automation library Should Be Equal ${inro}[name] __intro__ VAR ${init} = ${data}[__init__] - Should Start With ${init}[doc] Browser library can be taken into use with optional arguments: + Should Start With ${init}[doc] Browser library can be taken into use with optional arguments. Should Be Equal ${init}[name] __init__ Should Not Be Equal ${init}[doc] ${inro}[doc] [Teardown] Remove File ${OUTPUT_DIR}/translation.json