From ccf92c8cdfcdb584a8f332109239d01a0f9e4e85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9?= <41592183+Snooz82@users.noreply.github.com> Date: Tue, 20 Sep 2022 09:19:28 +0200 Subject: [PATCH] Topic/argument docs (#2308) ### News & Changes: #### Following should be backwards compatible: - [x] Deprecation of positional arguments for `Library Import` and `New Context` - [x] Deprecated positional arguments except the first few of `New Browser` and `New Persistent Context` - [x] Reordered named-only arguments alphabetically - [x] Updated all argument docs to be tables. - [x] Fixed some bad docs. - [x] New data type for switching and selecting browser, context and page. Now supports ``CURRENT`` == ``ACTIVE`` and ``ALL`` == ``ANY``. Not longer case sensitive. #### Backwards INCOMPATIBLE changes: - [x] Changed arguments for the expected assertion argument from `expected_value` or `expected_state` to `assertion_expected` as on all other getters for the following keywords: - [x] `Get Checkbox State` - [x] `Get Element Count` - [x] `Get Table Cell Index` - [x] `Get Table Row Index` - [x] `Keyboard Input` has now a `timedelta` as type for the `delay` argument. Before it was integer in milliseconds - [x] `Mouse Button` has now a `timedelta` as type for the `delay` argument. Before it was integer in milliseconds #### Bugfixes: - [x] `New Persistent Context` could not use `timeout` argument set to `0` - [x] `New Context` `viewport` argument can now be `${None}` to be able to open full screen browsers. #2054 --- Browser/browser.py | 113 +- Browser/keywords/browser_control.py | 101 +- Browser/keywords/cookie.py | 33 +- Browser/keywords/crawling.py | 15 +- Browser/keywords/device_descriptors.py | 5 +- Browser/keywords/evaluation.py | 51 +- Browser/keywords/getters.py | 394 +++---- Browser/keywords/interaction.py | 376 ++++--- Browser/keywords/network.py | 41 +- Browser/keywords/playwright_state.py | 973 +++++++++--------- Browser/keywords/promises.py | 14 +- Browser/keywords/runonfailure.py | 7 +- Browser/keywords/strict_mode.py | 6 +- Browser/keywords/waiter.py | 41 +- Browser/keywords/webapp_state.py | 31 +- Browser/utils/data_types.py | 24 +- atest/test/01_Browser_Management/goto.robot | 8 +- .../keyword_banner.robot | 18 +- .../02_Content_Keywords/virtual_mouse.robot | 2 +- utest/test_development_functionality.py | 4 +- 20 files changed, 1078 insertions(+), 1179 deletions(-) diff --git a/Browser/browser.py b/Browser/browser.py index 726c08ea7..c6ed891e2 100755 --- a/Browser/browser.py +++ b/Browser/browser.py @@ -29,6 +29,7 @@ from robot.errors import DataError # type: ignore from robot.libraries.BuiltIn import EXECUTION_CONTEXTS, BuiltIn # type: ignore from robot.running.arguments import PythonArgumentParser # type: ignore +from robot.running.arguments.typeconverters import TypeConverter # type: ignore from robot.utils import secs_to_timestr, timestr_to_secs # type: ignore from robotlibcore import DynamicCore # type: ignore @@ -692,43 +693,69 @@ class Browser(DynamicCore): _context_cache = ContextCache() _suite_cleanup_done = False + old_init_args = { + "timeout": timedelta, + "enable_playwright_debug": bool, + "auto_closing_level": AutoClosingLevel, + "retry_assertions_for": timedelta, + "run_on_failure": str, + "external_browser_executable": Optional[Dict[SupportedBrowsers, str]], + "jsextension": Optional[str], + "enable_presenter_mode": Union[HighLightElement, bool], + "playwright_process_port": Optional[int], + "strict": bool, + "show_keyword_call_banner": Optional[bool], + } + def __init__( self, - timeout: timedelta = timedelta(seconds=10), - enable_playwright_debug: bool = False, + *deprecated_pos_args, auto_closing_level: AutoClosingLevel = AutoClosingLevel.TEST, - retry_assertions_for: timedelta = timedelta(seconds=1), - run_on_failure: str = "Take Screenshot fail-screenshot-{index}", + enable_playwright_debug: bool = False, + enable_presenter_mode: Union[HighLightElement, bool] = False, external_browser_executable: Optional[Dict[SupportedBrowsers, str]] = None, jsextension: Optional[str] = None, - enable_presenter_mode: Union[HighLightElement, bool] = False, playwright_process_port: Optional[int] = None, - strict: bool = True, + retry_assertions_for: timedelta = timedelta(seconds=1), + run_on_failure: str = "Take Screenshot fail-screenshot-{index}", show_keyword_call_banner: Optional[bool] = None, + strict: bool = True, + timeout: timedelta = timedelta(seconds=10), ): """Browser library can be taken into use with optional arguments: - | ``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. | - | ``enable_playwright_debug`` | Enable low level debug information from the playwright tool. Mainly Useful for the library developers and for debugging purposes. | - | ``auto_closing_level`` | < ``TEST`` or ``SUITE`` or ``MANUAL`` > Configure context and page automatic closing. Default is ``TEST``, for more details, see `AutoClosingLevel` | - | ``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. | - | ``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. | - | ``jsextension`` | Path to Javascript module exposed as extra keywords. The module must be in CommonJS. | - | ``enable_presenter_mode`` | Automatic highlights to 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`. | - | ``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 ```et Strict Mode`` keyword. | - | ``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. | + | =Argument= | =Description= | + | ``*deprecated_pos_args`` | Positional arguments are deprecated for Library import. Please use named arguments instead. We will remove positional arguments after RoboCon 2023 Online in March. Old positional order was: ``timeout``, ``enable_playwright_debug``, ``auto_closing_level``, ``retry_assertions_for``, ``run_on_failure``, ``external_browser_executable``, ``jsextension``, ``enable_presenter_mode``, ``playwright_process_port``, ``strict``, ``show_keyword_call_banner``. | + | ``auto_closing_level`` | Configure context and page automatic closing. Default is ``TEST``, for more details, see `AutoClosingLevel` | + | ``enable_playwright_debug`` | Enable low level debug information from the playwright tool. Mainly Useful for the library developers and for debugging purposes. | + | ``enable_presenter_mode`` | Automatic highlights to 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`. | + | ``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. | + | ``jsextension`` | Path to Javascript module exposed as extra keywords. The module must be in CommonJS. | + | ``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. | + | ``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. | + | ``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 ```et 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. | """ - self.timeout = self.convert_timeout(timeout) - self.retry_assertions_for = self.convert_timeout(retry_assertions_for) self.ROBOT_LIBRARY_LISTENER = self - self._execution_stack: List[dict] = [] - self._running_on_failure_keyword = False - self._pause_on_failure: Set["Browser"] = set() - self.external_browser_executable: Dict[SupportedBrowsers, str] = ( - external_browser_executable or {} - ) - self._unresolved_promises: Set[Future] = set() + + old_args_list = list(self.old_init_args.items()) + pos_params = {} + for index, pos_arg in enumerate(deprecated_pos_args): + argument_name = old_args_list[index][0] + argument_type = old_args_list[index][1] + converted_pos = TypeConverter.converter_for(argument_type).convert( + argument_name, pos_arg + ) + pos_params[argument_name] = converted_pos + if pos_params: + logger.warn( + "Deprecated positional arguments are used in 'Library import of Browser library'. Please use named arguments instead." + ) + params = dict(locals()) + params = {**pos_params, **params} + self._playwright_state = PlaywrightState(self) libraries = [ self._playwright_state, @@ -747,22 +774,38 @@ def __init__( Waiter(self), WebAppState(self), ] + + self.timeout = self.convert_timeout(params["timeout"]) self.playwright = Playwright( - self, enable_playwright_debug, playwright_process_port + self, params["enable_playwright_debug"], playwright_process_port + ) + self._auto_closing_level: AutoClosingLevel = params["auto_closing_level"] + self.retry_assertions_for = self.convert_timeout(params["retry_assertions_for"]) + # Parsing needs keywords to be discovered. + self.external_browser_executable: Dict[SupportedBrowsers, str] = ( + params["external_browser_executable"] or {} ) - self._auto_closing_level = auto_closing_level + if params["jsextension"] is not None: + libraries.append(self._initialize_jsextension(params["jsextension"])) + self.presenter_mode: Union[HighLightElement, bool] = params[ + "enable_presenter_mode" + ] + self.strict_mode = params["strict"] + self.show_keyword_call_banner = params["show_keyword_call_banner"] + + self._execution_stack: List[dict] = [] + self._running_on_failure_keyword = False + self.pause_on_failure: Set[str] = set() + self._unresolved_promises: Set[Future] = set() self.current_arguments = () - if jsextension is not None: - libraries.append(self._initialize_jsextension(jsextension)) - self.presenter_mode = enable_presenter_mode - self.strict_mode = strict - self.show_keyword_call_banner = show_keyword_call_banner self.keyword_call_banner_add_style: str = "" self._keyword_formatters: dict = {} self._current_loglevel: Optional[str] = None + DynamicCore.__init__(self, libraries) - # Parsing needs keywords to be discovered. - self.run_on_failure_keyword = self._parse_run_on_failure_keyword(run_on_failure) + self.run_on_failure_keyword = self._parse_run_on_failure_keyword( + params["run_on_failure"] + ) def _parse_run_on_failure_keyword( self, keyword_name: Union[str, None] @@ -995,7 +1038,7 @@ def run_keyword(self, name, args, kwargs=None): except AssertionError as e: self.keyword_error() e.args = self._alter_keyword_error(e.args) - if self._pause_on_failure: + if self.pause_on_failure: sys.__stdout__.write(f"\n[ FAIL ] {e}") sys.__stdout__.write( "\n[Paused on failure] Press Enter to continue..\n" diff --git a/Browser/keywords/browser_control.py b/Browser/keywords/browser_control.py index a79ce415b..4492a0640 100644 --- a/Browser/keywords/browser_control.py +++ b/Browser/keywords/browser_control.py @@ -54,10 +54,9 @@ def go_back(self): def go_to(self, url: str, timeout: Optional[timedelta] = None): """Navigates to the given ``url``. - ``url`` URL to be navigated to. - - ``timeout`` time to wait page to load. If not defined - will use the library default timeout. + | =Arguments= | =Description= | + | ``url`` | URL to be navigated to. | + | ``timeout`` | time to wait page to load. If not defined will use the library default timeout. | [https://forum.robotframework.org/t//4291|Comment >>] """ @@ -103,44 +102,17 @@ def take_screenshot( ) -> str: """Takes a screenshot of the current window or element and saves it to disk. - ``filename`` Filename into which to save. The file will be saved into the robot framework - ${OUTPUTDIR}/browser/screenshot directory by default, but it can overwritten by providing - custom path or filename. String ``{index}`` in filename will be replaced with a rolling - number. Use this to not override filenames. If filename equals to EMBED (case insensitive), - then screenshot is embedded as Base64 image to the log.html. The image is saved temporally - to the disk and warning is displayed if removing the temporary file fails. - - The ${OUTPUTDIR}/browser/ 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 current viewport. - - ``fullPage`` When True, takes a screenshot of the full scrollable page, - instead of the currently visible viewport. Defaults to False. - - ``fileType`` <"png"|"jpeg"> Specify screenshot type, defaults to png. - - ``quality`` The quality of the image, between 0-100. Not applicable to png images. - - ``timeout`` Maximum time how long taking screenshot can last, defaults to library timeout. - Supports Robot Framework time format, like 10s or 1 min, pass 0 to disable timeout. - The default value can be changed by using the `Set Browser Timeout` keyword. - - ``crop`` Crops the taken screenshot to the given box. It takes same dictionary as returned from `Get BoundingBox`. - Cropping only works on page screenshot, so if 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 transitionend event. - - infinite animations are canceled to initial state, and then played over after the screenshot. - - ``mask`` Specify selectors that should be masked when the screenshot is taken. - Masked elements will be overlayed with a pink box ``#FF00FF`` that completely covers its bounding box. - Arguemnt can take a single selector string or a list of selector strings if multiple different elements should be masked. - - ``omitBackground`` Hides default white background and allows capturing screenshots with transparency. - Not applicable to jpeg images. + | =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 overwritten by providing custom path or filename. String ``{index}`` in filename will be replaced with a rolling number. Use this to not override filenames. If filename equals to EMBED (case insensitive), then screenshot is embedded as Base64 image to the log.html. The image is saved temporally to the disk and warning is displayed if removing the temporary file fails. The ${OUTPUTDIR}/browser/ 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 current viewport. | + | ``fullPage`` | When True, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to False. | + | ``fileType`` | <"png"|"jpeg"> Specify screenshot type, defaults to png. | + | ``quality`` | The quality of the image, between 0-100. Not applicable to png images. | + | ``timeout`` | Maximum time how long taking screenshot can last, defaults to library timeout. Supports Robot Framework time format, like 10s or 1 min, pass 0 to disable timeout. The default value can be changed by using the `Set Browser Timeout` keyword. | + | ``crop`` | Crops the taken screenshot to the given box. It takes same dictionary as returned from `Get BoundingBox`. Cropping only works on page screenshot, so if 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 transitionend event. - infinite animations are canceled to initial state, and then played over after the screenshot. | + | ``mask`` | Specify selectors that should be masked when the screenshot is taken. Masked elements will be overlayed with a pink box ``#FF00FF`` that completely covers its bounding box. Argument can take a single selector string or a list of selector strings if multiple different elements should be masked. | + | ``omitBackground`` | Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. | Keyword uses strict mode if selector is defined. See `Finding elements` for more details about strict mode. @@ -236,10 +208,8 @@ def _is_embed(self, filename: str) -> bool: def set_browser_timeout(self, timeout: timedelta) -> str: """Sets the timeout used by most input and getter keywords. - ``timeout`` Timeout of it is for current playwright context - and for new contexts. Supports Robot Framework - [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|time format] - . Returns the previous value of the timeout. + | =Arguments= | =Description= | + | ``timeout`` | Timeout of it is for current playwright context and for new contexts. Supports Robot Framework [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|time format] . Returns the previous value of the timeout. | Example: | ${old_timeout} = `Set Browser Timeout` 1m 30 seconds @@ -265,13 +235,13 @@ def set_browser_timeout(self, timeout: timedelta) -> str: def set_retry_assertions_for(self, timeout: timedelta) -> str: """Sets the timeout used in retrying assertions when they fail. - `Set Browser timeout` controls how long Playwright will perform - waiting in the node side, assertion retry will determine how long - Browser library will retry the playwright operation. Generally - assertion timeout should be longer than the timeout set by - `Set Browser timeout`. + Assertion retry timeout will determine how long Browser library will retry an assertion to be true. + + The other keyword `Set Browser timeout` controls how long Playwright + will perform waiting in the node side for Elements to fulfill the + requirements of the specific keyword. - Returns the previous value of the assertion retry. + Returns the previous value of the assertion retry timeout. Example: | `Set Browser Timeout` 10 seconds @@ -300,9 +270,9 @@ def show_keyword_banner( The banner can be controlled by an import setting of Browser library. (see `Importing` section) - ``show`` If `True` banner is shown on page. If `False` banner is not shown on page. If `None` banner is shown on page only when running in presenter mode. - - ``style`` Additional css styles to be applied to the banner. These styles are css settings and may override the existing ones for the banner. + | =Arguments= | =Description= | + | ``show`` | If `True` banner is shown on page. If `False` banner is not shown on page. If `None` banner is shown on page only when running in presenter mode. | + | ``style`` | Additional css styles to be applied to the banner. These styles are css settings and may override the existing ones for the banner. | Example: @@ -333,9 +303,9 @@ def set_viewport_size(self, width: int, height: int): so you should set the viewport size before navigating to the page with `New Context` before opening the page itself. - ``width`` Sets the width size. - - ``height`` Sets the height size. + | =Arguments= | =Description= | + | ``width`` | Sets the width size. | + | ``height`` | Sets the height size. | [https://forum.robotframework.org/t//4333|Comment >>] """ @@ -349,8 +319,8 @@ def set_viewport_size(self, width: int, height: int): def set_offline(self, offline: bool = True): """Toggles current Context's offline emulation. - ``offline`` Toggles the offline mode. Set to False to switch back - to online mode. Defaults to True. + | =Arguments= | =Description= | + | ``offline`` | Toggles the offline mode. Set to False to switch back to online mode. Defaults to True. | [https://forum.robotframework.org/t//4330|Comment >>] """ @@ -368,6 +338,11 @@ def set_geolocation( Accuracy of the location must be positive number and defaults to 0. When creating context, grant ``geolocation`` permission for pages to read its geolocation. + | =Arguments= | =Description= | + | ``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 | `New Context` permissions=${permissions} @@ -398,9 +373,9 @@ def reload(self): def grant_permissions(self, *permissions: Permission, origin: Optional[str] = None): """Grants permissions to the current context. - ```permissions``` is a list of permissions to grant. - Permissions can be one of the following: - geolocation, notifications, camera, microphone, + | =Arguments= | =Description= | + | ``permissions`` | is a list of permissions to grant. Permissions can be one of the following: geolocation, notifications, camera, microphone, | + | ``origin`` | The origin to grant permissions to, e.g. "https://example.com". | Example: | `New Context` diff --git a/Browser/keywords/cookie.py b/Browser/keywords/cookie.py index f2867efa0..37294e4ae 100644 --- a/Browser/keywords/cookie.py +++ b/Browser/keywords/cookie.py @@ -103,26 +103,17 @@ def add_cookie( ): """Adds a cookie to currently active browser context. - ``name`` Name of the cookie. - ``value`` Given value for the cookie. - - ``url`` Given url for the cookie. Defaults to None. Either ``url`` or ``domain`` / ``path`` pair must be set. - - ``domain`` Given domain for the cookie. Defaults to None. Either ``url`` or ``domain`` / ``path`` pair must be set. - - ``path`` Given path for the cookie. Defaults to None. Either ``url`` or ``domain`` / ``path`` pair must be set. - - ``expires`` Given expiry for the cookie. Can be of date format or unix time. 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. + | =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 ``domain`` / ``path`` pair must be set. | + | ``domain`` | Given domain for the cookie. Defaults to None. Either ``url`` or ``domain`` / ``path`` pair must be set. | + | ``path`` | Given path for the cookie. Defaults to None. Either ``url`` or ``domain`` / ``path`` pair must be set. | + | ``expires`` | Given expiry for the cookie. Can be of date format or unix time. 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. | Example: | `Add Cookie` foo bar http://address.com/path/to/site # Using url argument. @@ -186,7 +177,9 @@ def get_cookie( ) -> Union[DotDict, str]: """Returns information of cookie with ``name`` as a Robot Framework dot dictionary or a string. - ``cookie`` Name of the cookie to be retrieved. + | =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``. | If ``return_type`` is ``dictionary`` or ``dict`` then keyword returns a of Robot Framework [https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#accessing-list-and-dictionary-items|dot dictionary] diff --git a/Browser/keywords/crawling.py b/Browser/keywords/crawling.py index 77eb1df73..713240343 100644 --- a/Browser/keywords/crawling.py +++ b/Browser/keywords/crawling.py @@ -24,16 +24,11 @@ def crawl_site( returns list of crawled urls. - ``url`` is the page to start crawling from. - - ``page_crawl_keyword`` is the keyword that will be executed on every page. - 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 if the number of crawled pages goes over this. - - ``max_depth_to_crawl`` is the upper limit of consecutive links followed from the start page. - Crawling will stop if there are no more links under this depth. + | =Arguments= | =Description= | + | ``url`` | is the page to start crawling from. | + | ``page_crawl_keyword`` | is the keyword that will be executed on every page. 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 if the number of crawled pages goes over this. | + | ``max_depth_to_crawl`` | is the upper limit of consecutive links followed from the start page. Crawling will stop if there are no more links under this depth. | [https://forum.robotframework.org/t//4243|Comment >>] """ diff --git a/Browser/keywords/device_descriptors.py b/Browser/keywords/device_descriptors.py index 9d1618157..e58017253 100644 --- a/Browser/keywords/device_descriptors.py +++ b/Browser/keywords/device_descriptors.py @@ -40,9 +40,8 @@ def get_devices(self) -> Dict: def get_device(self, name: str) -> Dict: """Get a single device descriptor with name exactly matching name. - ``name`` Given 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= | =Description= | + | ``name`` | Given 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. | Allows a concise syntax to set website testing values to exact matches of specific mobile devices. diff --git a/Browser/keywords/evaluation.py b/Browser/keywords/evaluation.py index 188c79d1a..d44b10129 100644 --- a/Browser/keywords/evaluation.py +++ b/Browser/keywords/evaluation.py @@ -30,13 +30,9 @@ def execute_javascript(self, function: str, selector: str = "") -> Any: Executes given javascript on the page. - ``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 given a selector a function is necessary, with an argument - to capture the elementhandle. For example ``(element) => document.activeElement === element`` - See the `Finding elements` section for details about the selectors. + | =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 given a selector a function is necessary, with an argument to capture the elementhandle. For example ``(element) => document.activeElement === element`` See the `Finding elements` section for details about the selectors. | Same functionality can be replaced with newer ``Evaluate JavaScript`` Keyword: | - Execute JavaScript (elem) => elem.innerText = "abc" h1 @@ -75,20 +71,11 @@ def evaluate_javascript( ) -> Any: """Executes given javascript on the selected element(s) or on page. - ``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 elementHandle. 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. - This argument must be JSON serializable. ElementHandles are not supported. - - ``all_elements`` defines if only the single elementHandle found by ``selector`` is handed - over to the function or if set to ``True`` all found elements are handed over as array. + | =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 elementHandle. 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. This argument must be JSON serializable. ElementHandles are not supported. | + | ``all_elements`` | defines if only the single elementHandle found by ``selector`` is handed over to the function or if set to ``True`` all found elements are handed over as array. | Example with ``all_elements=True``: | ${texts}= Evaluate JavaScript button @@ -138,17 +125,12 @@ def highlight_elements( ): """Adds a highlight to elements matched by the ``selector``. Provides a style adjustment. - ``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. - - ``width`` Sets the width of the higlight 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`` + | =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. | + | ``width`` | Sets the width of the higlight 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`` | Keyword does not fail if selector resolves to multiple elements. @@ -175,7 +157,8 @@ def highlight_elements( def add_style_tag(self, content: str): """Adds a