From ed3749976155830872c600f5c11473ffa007186d Mon Sep 17 00:00:00 2001 From: Karan Gathani Date: Thu, 6 Jun 2024 11:08:00 -0700 Subject: [PATCH 01/11] Add documentation for all public methods and classes in controls --- CHANGELOG.md | 2 + shiny/playwright/controls/_controls.py | 2527 ++++++++++++++++++++++-- 2 files changed, 2356 insertions(+), 173 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c01bbc04d..b062b3e77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### New features +* Expose shiny.pytest, shiny.run and shiny.playwright modules that allow users to testing their Shiny apps. (#1448) + * Added busy indicators to provide users with a visual cue when the server is busy calculating outputs or otherwise serving requests to the client. More specifically, a spinner is shown on each calculating/recalculating output, and a pulsing banner is shown at the top of the page when the app is otherwise busy. Use the new `ui.busy_indicator.options()` function to customize the appearance of the busy indicators and `ui.busy_indicator.use()` to disable/enable them. (#918) * Added support for creating modules using Shiny Express syntax, and using modules in Shiny Express apps. (#1220) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index b7032ea85..387fd9a5d 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -111,6 +111,22 @@ def set_text( delay: OptionalFloat = None, timeout: Timeout = None, ) -> None: + """ + Sets the text of an element. + + Parameters + ---------- + loc + The locator of the element. + text + The text to set. + delay + The delay between key presses in milliseconds. + Defaults to None. + timeout + The maximum time to wait for the text to be set. + Defaults to None. + """ # TODO-future; Composable set() method loc.fill("", timeout=timeout) # Reset the value loc.type(text, delay=delay, timeout=timeout) # Type the value @@ -133,10 +149,16 @@ class _InputBaseP(Protocol): class _InputWithContainerP(_InputBaseP, Protocol): + """ A mixin class representing inputs with a container. """ + loc_container: Locator + """ + `loc_container` is the locator of the container of the input. + """ class _InputBase: + """ A base class representing inputs. """ # timeout: Timeout id: str loc: Locator @@ -226,6 +248,21 @@ def __init__( class _InputWithLabel(_InputWithContainer): + """ A mixin class representing inputs with a label. """ + + loc: Locator + """ + `loc` is the locator of the input. + """ + loc_container: Locator + """ + `loc_container` is the locator of the container of the input. + """ + loc_label: Locator + """ + `loc_label` is the locator of the label of the input. + """ + def __init__( self, page: Page, @@ -235,6 +272,23 @@ def __init__( loc_container: InitLocator = "div.shiny-input-container", loc_label: InitLocator | None = None, ) -> None: + """ + Initializes the input with a label. + + Parameters + ---------- + page + The page where the input is located. + id + The id of the input. + loc + The locator of the input. + loc_container + The locator of the container of the input. + loc_label + The locator of the label of the input. + Defaults to None. + """ super().__init__( page, id=id, @@ -254,6 +308,17 @@ def expect_label( *, timeout: Timeout = None, ) -> None: + """ + Expect the label of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the label. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ playwright_expect(self.loc_label).to_have_text(value, timeout=timeout) @@ -313,16 +378,39 @@ def expect_width( class _SetTextM: def set(self: _InputBaseP, value: str, *, timeout: Timeout = None) -> None: + """ + Sets the text of the input. + + Parameters + ---------- + value + The text to set. + timeout + The maximum time to wait for the text to be set. + Defaults to None. + """ set_text(self.loc, value, timeout=timeout) class _ExpectTextInputValueM: + """ A mixin class representing text input values. """ def expect_value( self: _InputBaseP, value: PatternOrStr, *, timeout: Timeout = None, ) -> None: + """ + Expect the value of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the input. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ playwright_expect(self.loc).to_have_value(value, timeout=timeout) @@ -332,15 +420,18 @@ class InputNumeric( _WidthLocM, _InputWithLabel, ): - # id: str, - # label: TagChild, - # value: float, - # *, - # min: Optional[float] = None, - # max: Optional[float] = None, - # step: Optional[float] = None, - # width: Optional[str] = None, + """ Input numeric control for :func: `~shiny.ui.input_numeric` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes the input numeric. + + Parameters + ---------- + page + The page where the input numeric is located. + id + The id of the input numeric. + """ super().__init__( page, id=id, @@ -353,6 +444,17 @@ def expect_min( *, timeout: Timeout = None, ) -> None: + """ + Expect the min attribute of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the min attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "min", value=value, timeout=timeout) def expect_max( @@ -361,6 +463,17 @@ def expect_max( *, timeout: Timeout = None, ) -> None: + """ + Expect the max attribute of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the max attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "max", value=value, timeout=timeout) def expect_step( @@ -369,6 +482,17 @@ def expect_step( *, timeout: Timeout = None, ) -> None: + """ + Expect the step attribute of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the step attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "step", value=value, timeout=timeout) @@ -379,6 +503,17 @@ def expect_spellcheck( *, timeout: Timeout = None, ) -> None: + """ + Expect the spellcheck attribute of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the spellcheck attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ # self.spellcheck.expect_to_have_value(value, timeout=timeout) expect_attribute_to_have_value( self.loc, "spellcheck", value=value, timeout=timeout @@ -392,6 +527,17 @@ def expect_placeholder( *, timeout: Timeout = None, ) -> None: + """ + Expect the placeholder attribute of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the placeholder attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.loc, "placeholder", value=value, timeout=timeout ) @@ -404,6 +550,17 @@ def expect_autocomplete( *, timeout: Timeout = None, ) -> None: + """ + Expect the autocomplete attribute of the input to have a specific value. + + Parameters + ---------- + value + The expected value of the autocomplete attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.loc, "autocomplete", value=value, timeout=timeout ) @@ -418,15 +575,31 @@ class InputText( _ExpectSpellcheckAttrM, _InputWithLabel, ): - # id: str, - # label: TagChild, - # value: str = "", - # *, - # width: Optional[str] = None, - # placeholder: Optional[str] = None, - # autocomplete: Optional[str] = "off", - # spellcheck: Optional[Literal["true", "false"]] = None, + """ Input text control for :func: `~shiny.ui.input_text` """ + + loc: Locator + """ + The locator of the input. + """ + loc_container: Locator + """ + The locator of the container of the input. + """ + loc_label: Locator + """ + The locator of the label of the input. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes the input text. + + Parameters + ---------- + page + The page where the input text is located. + id + The id of the input text. + """ super().__init__( page, id=id, @@ -440,15 +613,25 @@ class InputPassword( _ExpectPlaceholderAttrM, _InputWithLabel, ): - # id: str, - # label: TagChild, - # value: str = "", - # *, - # width: Optional[str] = None, - # placeholder: Optional[str] = None, + """ Input password control for :func: `~shiny.ui.input_password` """ + + loc: Locator + """ + The locator of the input. + """ ... def __init__(self, page: Page, id: str) -> None: + """ + Initializes the input password. + + Parameters + ---------- + page + The page where the input password is located. + id + The id of the input password. + """ super().__init__( page, id=id, @@ -463,6 +646,17 @@ def expect_width( *, timeout: Timeout = None, ) -> None: + """ + Expect the width attribute of the input password to have a specific value. + + Parameters + ---------- + value + The expected value of the width attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_to_have_style(self.loc_container, "width", value, timeout=timeout) @@ -477,20 +671,23 @@ class InputTextArea( _ExpectSpellcheckAttrM, _InputWithLabel, ): - # id: str, - # label: TagChild, - # value: str = "", - # width: Optional[str] = None, - # height: Optional[str] = None, - # cols: Optional[int] = None, - # rows: Optional[int] = None, - # placeholder: Optional[str] = None, - # resize: Optional[ - # Literal["none", "both", "horizontal", "vertical"] - # ] = None, - # autocomplete: Optional[str] = None, - # spellcheck: Optional[Literal["true", "false"]] = None, + """ Input text area control for :func: `~shiny.ui.input_text_area` """ + + loc: Locator + """ + The locator of the input. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes the input text area. + + Parameters + ---------- + page + The page where the input text area is located. + id + The id of the input text area. + """ super().__init__( page, id=id, @@ -498,6 +695,17 @@ def __init__(self, page: Page, id: str) -> None: ) def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: + """ + Expect the width attribute of the input text area to have a specific value. + + Parameters + ---------- + value + The expected value of the width attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ if value is None: expect_to_have_style(self.loc_container, "width", None, timeout=timeout) expect_to_have_style(self.loc, "width", "100%", timeout=timeout) @@ -506,12 +714,45 @@ def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: expect_to_have_style(self.loc, "width", None, timeout=timeout) def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: + """ + Expect the height attribute of the input text area to have a specific value. + + Parameters + ---------- + value + The expected value of the height attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_to_have_style(self.loc, "height", value, timeout=timeout) def expect_cols(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the cols attribute of the input text area to have a specific value. + + Parameters + ---------- + value + The expected value of the cols attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "cols", value=value, timeout=timeout) def expect_rows(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the rows attribute of the input text area to have a specific value. + + Parameters + ---------- + value + The expected value of the rows attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "rows", value=value, timeout=timeout) def expect_resize( @@ -520,6 +761,17 @@ def expect_resize( *, timeout: Timeout = None, ) -> None: + """ + Expect the resize attribute of the input text area to have a specific value. + + Parameters + ---------- + value + The expected value of the resize attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "resize", value=value, timeout=timeout) def expect_autoresize( @@ -528,6 +780,17 @@ def expect_autoresize( *, timeout: Timeout = None, ) -> None: + """ + Expect the autoresize attribute of the input text area to have a specific value. + + Parameters + ---------- + value + The expected value of the autoresize attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ _expect_class_value( self.loc, "textarea-autoresize", @@ -541,8 +804,17 @@ class _InputSelectBase( _InputWithLabel, ): loc_selected: Locator + """ + `loc_selected` is the locator of the selected option of the input select. + """ loc_choices: Locator + """ + `loc_choices` is the locator of the choices of the input select. + """ loc_choice_groups: Locator + """ + `loc_choice_groups` is the locator of the choice groups of the input select. + """ def __init__( self, @@ -551,6 +823,19 @@ def __init__( *, select_class: str = "", ) -> None: + """ + Initializes the input select. + + Parameters + ---------- + page + The page where the input select is located. + id + The id of the input select. + select_class + The class of the select element. + Defaults to "". + """ super().__init__( page, id=id, @@ -566,6 +851,17 @@ def set( *, timeout: Timeout = None, ) -> None: + """ + Sets the selected option(s) of the input select. + + Parameters + ---------- + selected + The value(s) of the selected option(s). + timeout + The maximum time to wait for the selection to be set. + Defaults to None. + """ if isinstance(selected, str): selected = [selected] self.loc.select_option(value=selected, timeout=timeout) @@ -577,6 +873,17 @@ def expect_choices( *, timeout: Timeout = None, ) -> None: + """ + Expect the choices of the input select to be in order. + + Parameters + ---------- + choices + The expected choices of the input select. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ """Expect choices to be in order""" # Playwright doesn't like lists of size 0. Instead, check for empty locator if len(choices) == 0: @@ -598,6 +905,17 @@ def expect_selected( *, timeout: Timeout = None, ) -> None: + """ + Expect the selected option(s) of the input select to be in order. + + Parameters + ---------- + selected + The expected value(s) of the selected option(s). + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ """Expect choices to be in order""" # Playwright doesn't like lists of size 0 if isinstance(selected, list) and len(selected) == 0: @@ -626,6 +944,17 @@ def expect_choice_groups( *, timeout: Timeout = None, ) -> None: + """ + Expect the choice groups of the input select to be in order. + + Parameters + ---------- + choice_groups + The expected choice groups of the input select. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ """Expect choices to be in order""" # Playwright doesn't like lists of size 0. Instead, use `None` if len(choice_groups) == 0: @@ -648,6 +977,17 @@ def expect_choice_labels( *, timeout: Timeout = None, ) -> None: + """ + Expect the choice labels of the input select to be in order. + + Parameters + ---------- + choice_labels + The expected choice labels of the input select. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ # Playwright doesn't like lists of size 0. Instead, use `None` if len(choice_labels) == 0: playwright_expect(self.loc_choices).to_have_count(0, timeout=timeout) @@ -656,9 +996,31 @@ def expect_choice_labels( # multiple: bool = False, def expect_multiple(self, multiple: bool, *, timeout: Timeout = None) -> None: + """ + Expect the input select to allow multiple selections. + + Parameters + ---------- + multiple + Whether the input select allows multiple selections. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ _expect_multiple(self.loc, multiple, timeout=timeout) def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the size attribute of the input select to have a specific value. + + Parameters + ---------- + value + The expected value of the size attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.loc, "size", @@ -668,15 +1030,18 @@ def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: class InputSelect(_InputSelectBase): - # id: str, - # label: TagChild, - # choices: SelectChoicesArg, - # selected: Optional[Union[str, list[str]]] = None, - # multiple: bool = False, - # selectize: bool = False, - # width: Optional[str] = None, - # size: Optional[str] = None, + """ Input select control for :func: `~shiny.ui.input_select` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes the input select. + + Parameters + ---------- + page + The page where the input select is located. + id + The id of the input select. + """ super().__init__( page, id=id, @@ -685,6 +1050,17 @@ def __init__(self, page: Page, id: str) -> None: # selectize: bool = False, def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: + """ + Expect the input select to be selectize. + + Parameters + ---------- + selectize + Whether the input select is selectize. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ # class_=None if selectize else "form-select", _expect_class_value( self.loc, @@ -695,6 +1071,7 @@ def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: class InputSelectize(_InputSelectBase): + """ Input selectize control for :func: `~shiny.ui.input_selectize` """ def __init__(self, page: Page, id: str) -> None: super().__init__( page, @@ -715,6 +1092,15 @@ def expect_label( self.expect.to_have_text(value, timeout=timeout) def click(self, *, timeout: Timeout = None, **kwargs: object) -> None: + """ + Clicks the input action. + + Parameters + ---------- + timeout + The maximum time to wait for the input action to be clicked. + Defaults to None. + """ self.loc.click(timeout=timeout, **kwargs) # pyright: ignore[reportArgumentType] @@ -722,15 +1108,22 @@ class InputActionButton( _WidthLocM, _InputActionBase, ): - # label: TagChild, - # icon: TagChild = None, - # width: Optional[str] = None, - + """ Input action button control for :func: `~shiny.ui.input_action_button` """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initializes the input action button. + + Parameters + ---------- + page + The page where the input action button is located. + id + The id of the input action button. + """ super().__init__( page, id=id, @@ -739,11 +1132,22 @@ def __init__( class InputDarkMode(_InputBase): + """ Input dark mode control for :func: `~shiny.ui.input_dark_mode` """ def __init__( self, page: Page, id: Optional[str] | None, ) -> None: + """ + Initializes the input dark mode. + + Parameters + ---------- + page + The page where the input dark mode is located. + id + The id of the input dark mode. + """ id_selector = "" if id is None else f"#{id}" super().__init__( @@ -753,21 +1157,63 @@ def __init__( ) def click(self, *, timeout: Timeout = None): + """ + Clicks the input dark mode. + + Parameters + ---------- + timeout + The maximum time to wait for the input dark mode to be clicked. + Defaults to None. + """ self.loc.click(timeout=timeout) return self def expect_mode(self, value: str, *, timeout: Timeout = None): + """ + Expect the mode attribute of the input dark mode to have a specific value. + + Parameters + ---------- + value + The expected value of the mode attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value(self.loc, "mode", value=value, timeout=timeout) self.expect_page_mode(value, timeout=timeout) return self def expect_page_mode(self, value: str, *, timeout: Timeout = None): + """ + Expect the page mode to have a specific value. + + Parameters + ---------- + value + The expected value of the page mode. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.page.locator("html"), "data-bs-theme", value=value, timeout=timeout ) return self def expect_wc_attribute(self, value: str, *, timeout: Timeout = None): + """ + Expect the wc attribute of the input dark mode to have a specific value. + + Parameters + ---------- + value + The expected value of the wc attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.loc, "attribute", value=value, timeout=timeout ) @@ -778,22 +1224,28 @@ class InputTaskButton( _WidthLocM, _InputActionBase, ): + """ Input task button control for :func: `~shiny.ui.input_task_button` """ + + loc: Locator + """ + The locator of the input task button. + """ # TODO-Karan: Test auto_reset functionality - # id: str, - # label: TagChild, - # *args: TagChild, - # icon: TagChild = None, - # label_busy: TagChild = "Processing...", - # icon_busy: TagChild | MISSING_TYPE = MISSING, - # width: Optional[str] = None, - # type: Optional[str] = "primary", - # auto_reset: bool = True, - # **kwargs: TagAttrValue, def __init__( self, page: Page, id: str, ) -> None: + """ + Initializes the input task button. + + Parameters + ---------- + page + The page where the input task button is located. + id + The id of the input task button. + """ super().__init__( page, id=id, @@ -803,6 +1255,17 @@ def __init__( def expect_state( self, value: Literal["ready", "busy"] | str, *, timeout: Timeout = None ): + """ + Expect the state of the input task button to have a specific value. + + Parameters + ---------- + value + The expected value of the state. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.loc.locator("> bslib-switch-inline"), name="case", @@ -811,22 +1274,79 @@ def expect_state( ) def expect_label(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expect the label of the input task button to have a specific value. + + Parameters + ---------- + value + The expected value of the label. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ self.expect_label_ready(value, timeout=timeout) def expect_label_ready(self, value: PatternOrStr, *, timeout: Timeout = None): + """ + Expect the label of the input task button to have a specific value. + + Parameters + ---------- + value + The expected value of the label. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ self.expect_label_state("ready", value, timeout=timeout) def expect_label_busy(self, value: PatternOrStr, *, timeout: Timeout = None): + """ + Expect the label of the input task button to have a specific value. + + Parameters + ---------- + value + The expected value of the label. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ self.expect_label_state("busy", value, timeout=timeout) def expect_label_state( self, state: str, value: PatternOrStr, *, timeout: Timeout = None ): + """ + Expect the label of the input task button to have a specific value. + + Parameters + ---------- + state + The state of the input task button. + value + The expected value of the label. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ playwright_expect( self.loc.locator(f"> bslib-switch-inline > span[slot='{state}']") ).to_have_text(value, timeout=timeout) def expect_auto_reset(self, value: bool, timeout: Timeout = None): + """ + Expect the auto-reset attribute of the input task button to have a specific value. + + Parameters + ---------- + value + The expected value of the auto-reset attribute. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ expect_attribute_to_have_value( self.loc, name="data-auto-reset", @@ -836,14 +1356,27 @@ def expect_auto_reset(self, value: bool, timeout: Timeout = None): class InputActionLink(_InputActionBase): - # label: TagChild, - # icon: TagChild = None, + """ Input action link control for :func: `~shiny.ui.input_action_link` """ + loc: Locator + """ + The locator of the input action link. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initializes the input action link. + + Parameters + ---------- + page + The page where the input action link is located. + id + The id of the input action link. + """ super().__init__( page, id=id, @@ -860,12 +1393,23 @@ class _InputCheckboxBase( _WidthContainerM, _InputWithLabel, ): - # label: TagChild - # value: bool = False - # width: Optional[str] = None def __init__( self, page: Page, id: str, loc: InitLocator, loc_label: str | None ) -> None: + """ + Initializes the input checkbox. + + Parameters + ---------- + page + The page where the input checkbox is located. + id + The id of the input checkbox. + loc + The locator of the input checkbox. + loc_label + The locator of the label of the input checkbox. + """ super().__init__( page, id=id, @@ -874,6 +1418,17 @@ def __init__( ) def set(self, value: bool, *, timeout: Timeout = None, **kwargs: object) -> None: + """ + Sets the input checkbox. + + Parameters + ---------- + value + The value of the input checkbox. + timeout + The maximum time to wait for the input checkbox to be set. + Defaults to None. + """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) self.loc.set_checked( @@ -881,11 +1436,31 @@ def set(self, value: bool, *, timeout: Timeout = None, **kwargs: object) -> None ) def toggle(self, *, timeout: Timeout = None, **kwargs: object) -> None: + """ + Toggles the input checkbox. + + Parameters + ---------- + timeout + The maximum time to wait for the input checkbox to be toggled. + Defaults to None. + """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) self.loc.click(timeout=timeout, **kwargs) # pyright: ignore[reportArgumentType] def expect_checked(self, value: bool, *, timeout: Timeout = None) -> None: + """ + Expect the input checkbox to be checked. + + Parameters + ---------- + value + Whether the input checkbox is checked. + timeout + The maximum time to wait for the expectation to be fulfilled. + Defaults to None. + """ if value: self.expect.to_be_checked(timeout=timeout) else: @@ -893,11 +1468,35 @@ def expect_checked(self, value: bool, *, timeout: Timeout = None) -> None: class InputCheckbox(_InputCheckboxBase): + """ Input checkbox control for :func: `~shiny.ui.input_checkbox` """ + + loc: Locator + """ + The locator of the input checkbox. + """ + loc_container: Locator + """ + The locator of the container of the input checkbox. + """ + loc_label: Locator + """ + The locator of the label of the input checkbox. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initializes the input checkbox. + + Parameters + ---------- + page + The page where the input checkbox is located. + id + The id of the input checkbox. + """ super().__init__( page, id=id, @@ -907,11 +1506,35 @@ def __init__( class InputSwitch(_InputCheckboxBase): + """ Input switch control for :func: `~shiny.ui.input_switch` """ + + loc: Locator + """ + The locator of the input switch. + """ + loc_container: Locator + """ + The locator of the container of the input switch. + """ + loc_label: Locator + """ + The locator of the label of the input switch. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initializes the input switch. + + Parameters + ---------- + page + The page where the input switch is located. + id + The id of the input switch. + """ super().__init__( page, id=id, @@ -926,12 +1549,30 @@ def assert_arr_is_unique( arr: ListPatternOrStr, msg: str, ) -> None: + """ + Assert that the array is unique. + + Parameters + ---------- + arr : ListPatternOrStr + The array to check. + msg : str + The error message. + """ assert len(arr) == len(list(dict.fromkeys(arr))), msg @staticmethod def checked_css_str( is_checked: bool | MISSING_TYPE = MISSING, ) -> str: + """ + Get the CSS string for checked elements. + + Parameters + ---------- + is_checked : bool | MISSING_TYPE, optional + Whether the elements are checked, by default MISSING + """ if is_missing(is_checked): return "" if is_checked: @@ -952,6 +1593,28 @@ def expect_locator_contains_values_in_list( timeout: Timeout = None, key: str = "value", ) -> None: + """ + Expect the locator to contain the values in the list. + + Parameters + ---------- + page : Page + The Playwright page. + loc_container : Locator + The container locator. + el_type : str + The element type. + arr_name : str + The array name. + arr : list[str] + The expected values. + is_checked : bool | MISSING_TYPE, optional + Whether the elements are checked, by default MISSING + timeout : Timeout, optional + The timeout for the expectation, by default None + key : str, optional + The key, by default "value" + """ # Make sure the locator contains all of `arr` assert_type(arr, typing.List[str]) @@ -1015,6 +1678,28 @@ def expect_locator_values_in_list( timeout: Timeout = None, key: str = "value", ) -> None: + """ + Expect the locator to contain the values in the list. + + Parameters + ---------- + page : Page + The Playwright page. + loc_container : Locator + The container locator. + el_type : Locator | str + The element type locator. + arr_name : str + The array name. + arr : ListPatternOrStr + The expected values. + is_checked : bool | MISSING_TYPE, optional + Whether the elements are checked, by default MISSING + timeout : Timeout, optional + The timeout for the expectation, by default None + key : str, optional + The key, by default "value" + """ # Make sure the locator has exactly `arr` values # Make sure the locator has len(uniq_arr) input elements @@ -1092,6 +1777,16 @@ def expect_choice_labels( *, timeout: Timeout = None, ) -> None: + """ + Expect the labels of the choices. + + Parameters + ---------- + labels : ListPatternOrStr + The expected labels. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ if len(labels) == 1: labels_val = labels[0] else: @@ -1102,6 +1797,16 @@ def expect_choice_labels( ) def expect_inline(self, inline: bool, *, timeout: Timeout = None) -> None: + """ + Expect the input to be inline. + + Parameters + ---------- + inline : bool + Whether the input is inline. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ _expect_class_value( self.loc_container, "shiny-input-container-inline", @@ -1124,6 +1829,16 @@ def __init__( page: Page, id: str, ) -> None: + """ + Initialize the InputCheckboxGroup. + + Parameters + ---------- + page : Page + The Playwright page. + id : str + The id of the checkbox group. + """ super().__init__( page, id=id, @@ -1159,6 +1874,16 @@ def set( timeout: Timeout = None, **kwargs: object, ) -> None: + """ + Set the selected checkboxes. + + Parameters + ---------- + selected : list[str] + The values of the selected checkboxes. + timeout : Timeout, optional + The timeout for the action, by default None. + """ # Having an arr of size 0 is allowed. Will uncheck everything assert_type(selected, typing.List[str]) @@ -1201,6 +1926,16 @@ def expect_choices( *, timeout: Timeout = None, ) -> None: + """ + Expect the checkbox choices. + + Parameters + ---------- + choices : ListPatternOrStr + The expected choices. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, loc_container=self.loc_container, @@ -1216,6 +1951,16 @@ def expect_selected( *, timeout: Timeout = None, ) -> None: + """ + Expect the selected checkboxes. + + Parameters + ---------- + selected : ListPatternOrStr + The expected values of the selected checkboxes. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ # Playwright doesn't like lists of size 0 if len(selected) == 0: playwright_expect(self.loc_selected).to_have_count(0, timeout=timeout) @@ -1236,17 +1981,34 @@ class InputRadioButtons( _WidthContainerM, _RadioButtonCheckboxGroupBase, ): - # id: str, - # label: TagChild, - # choices: ChoicesArg, - # selected: Optional[str] = None, - # inline: bool = False, - # width: Optional[str] = None, + """ Input radio buttons control for :func: `~shiny.ui.input_radio_buttons` """ + + loc_selected: Locator + """ + The locator of the selected radio button. + """ + loc_choices: Locator + """ + The locator of the radio button choices. + """ + loc_choice_labels: Locator + """ + The locator of the labels of the radio button choices. + """ def __init__( self, page: Page, id: str, ) -> None: + """Initialize the InputRadioButtons. + + Parameters + ---------- + page : Page + The Playwright page. + id : str + The id of the radio buttons. + """ super().__init__( page, id=id, @@ -1281,6 +2043,16 @@ def set( timeout: Timeout = None, **kwargs: object, ) -> None: + """ + Set the selected radio button. + + Parameters + ---------- + selected : str + The value of the selected radio button. + timeout : Timeout, optional + The timeout for the action, by default None. + """ assert_type(selected, str) # Only need to set. # The Browser will _unset_ the previously selected radio button @@ -1294,6 +2066,16 @@ def expect_choices( *, timeout: Timeout = None, ) -> None: + """ + Expect the radio button choices. + + Parameters + ---------- + choices : ListPatternOrStr + The expected choices. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, loc_container=self.loc_container, @@ -1309,6 +2091,16 @@ def expect_selected( *, timeout: Timeout = None, ) -> None: + """ + Expect the selected radio button. + + Parameters + ---------- + selected : PatternOrStr | None + The expected value of the selected radio button. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ # Playwright doesn't like lists of size 0. Instead, use `None` if selected is None: playwright_expect(self.loc_selected).to_have_count(0, timeout=timeout) @@ -1321,9 +2113,20 @@ class InputFile( # _ExpectPlaceholderAttrM, _InputWithLabel, ): + """ Input file control for :func: `~shiny.ui.input_file` """ + loc_button: Locator + """ + The locator of the button. + """ loc_file_display: Locator + """ + The locator of the file display. + """ loc_progress: Locator + """ + The locator of the progress bar. + """ # id: str, # label: TagChild, @@ -1343,6 +2146,16 @@ def __init__( page: Page, id: str, ) -> None: + """ + Initialize the InputFile. + + Parameters + ---------- + page : Page + The Playwright page. + id : str + The id of the file input. + """ super().__init__( page, id=id, @@ -1365,6 +2178,18 @@ def set( timeout: Timeout = None, expect_complete_timeout: Timeout = 30 * 1000, ) -> None: + """ + Set the file upload. + + Parameters + ---------- + file_path : str | pathlib.Path | FilePayload | list[str | pathlib.Path] | list[FilePayload] + The path to the file to upload. + timeout : Timeout, optional + The timeout for the action, by default None. + expect_complete_timeout : Timeout, optional + The timeout for the expectation that the upload is complete, by default 30 * 1000. + """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) self.loc.set_input_files(file_path, timeout=timeout) @@ -1377,6 +2202,14 @@ def expect_complete( *, timeout: Timeout = None, ) -> None: + """ + Expect the file upload to be complete. + + Parameters + ---------- + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_to_have_style(self.loc_progress, "width", "100%", timeout=timeout) # TODO-future; Test multiple file upload @@ -1389,6 +2222,16 @@ def expect_accept( *, timeout: Timeout = None, ) -> None: + """ + Expect the `accept` attribute to have a specific value. + + Parameters + ---------- + accept : list[str] | AttrValue + The expected value of the `accept` attribute. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ if isinstance(accept, list): accept = ",".join(accept) expect_attribute_to_have_value(self.loc, "accept", accept, timeout=timeout) @@ -1402,6 +2245,16 @@ def expect_button_label( *, timeout: Timeout = None, ) -> None: + """ + Expect the button label to have a specific value. + + Parameters + ---------- + button_label : PatternOrStr + The expected value of the button label. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ playwright_expect(self.loc_button).to_have_text(button_label, timeout=timeout) def expect_capture( @@ -1410,6 +2263,16 @@ def expect_capture( *, timeout: Timeout = None, ) -> None: + """ + Expect the `capture` attribute to have a specific value. + + Parameters + ---------- + capture : Literal["environment", "user"] | None + The expected value of the `capture` attribute. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value(self.loc, "capture", capture, timeout=timeout) def expect_placeholder(self, value: AttrValue, *, timeout: Timeout = None) -> None: @@ -1419,31 +2282,35 @@ def expect_placeholder(self, value: AttrValue, *, timeout: Timeout = None) -> No class _InputSliderBase(_WidthLocM, _InputWithLabel): - # id: str, - # label: TagChild, - # min: SliderValueArg, - # max: SliderValueArg, - # value: Union[SliderValueArg, Iterable[SliderValueArg]], - # step: Optional[SliderStepArg] = None, - # ticks: bool = True, - # animate: Union[bool, AnimationOptions] = False, - # width: Optional[str] = None, - # sep: str = ",", - # pre: Optional[str] = None, - # post: Optional[str] = None, - # time_format: Optional[str] = None, - # timezone: Optional[str] = None, - # drag_range: bool = True, loc_irs: Locator + """ + The locator of the input slider. + """ loc_irs_ticks: Locator + """ + The locator of the input slider ticks. + """ loc_play_pause: Locator + """ + The locator of the play/pause button. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initialize the InputSlider. + + Parameters + ---------- + page : Page + The Playwright page. + id : str + The id of the slider. + """ super().__init__( page, id=id, @@ -1461,6 +2328,16 @@ def expect_tick_labels( *, timeout: Timeout = None, ) -> None: + """ + Expect the tick labels of the input slider. + + Parameters + ---------- + value : ListPatternOrStr | None + The expected tick labels. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ if value is None: playwright_expect(self.loc_irs_ticks).to_have_count(0) return @@ -1468,6 +2345,16 @@ def expect_tick_labels( playwright_expect(self.loc_irs_ticks).to_have_text(value, timeout=timeout) def expect_animate(self, exists: bool, *, timeout: Timeout = None) -> None: + """ + Expect the animate button to exist. + + Parameters + ---------- + exists : bool + Whether the animate button should exist. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ animate_count = 1 if exists else 0 playwright_expect(self.loc_play_pause).to_have_count(animate_count) @@ -1503,6 +2390,14 @@ def expect_animate_options( # become `play` over and over again. Instead, have explicit `play` and `pause` # methods. def click_play(self, *, timeout: Timeout = None) -> None: + """ + Click the play button. + + Parameters + ---------- + timeout : Timeout, optional + The timeout for the action, by default None. + """ self.loc_container.wait_for(state="visible", timeout=timeout) self.loc_container.scroll_into_view_if_needed(timeout=timeout) _expect_class_value( @@ -1511,6 +2406,14 @@ def click_play(self, *, timeout: Timeout = None) -> None: self.loc_play_pause.click() def click_pause(self, *, timeout: Timeout = None) -> None: + """ + Click the pause button. + + Parameters + ---------- + timeout : Timeout, optional + The timeout for the action, by default None. + """ self.loc_container.wait_for(state="visible", timeout=timeout) self.loc_container.scroll_into_view_if_needed(timeout=timeout) _expect_class_value( @@ -1519,36 +2422,106 @@ def click_pause(self, *, timeout: Timeout = None) -> None: self.loc_play_pause.click() def expect_min(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `min` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-min", value=value, timeout=timeout ) def expect_max(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `max` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-max", value=value, timeout=timeout ) def expect_step(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `step` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-step", value=value, timeout=timeout ) def expect_ticks(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `data-ticks` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-grid", value=value, timeout=timeout ) def expect_sep(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `data-sep` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-prettify-separator", value=value, timeout=timeout ) def expect_pre(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `data-pre` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-prefix", value=value, timeout=timeout ) def expect_post(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Expect the input element to have the expected `data-post` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Timeout, optional + The timeout for the expectation, by default None. + """ expect_attribute_to_have_value( self.loc, "data-postfix", value=value, timeout=timeout ) @@ -1559,16 +2532,46 @@ def expect_post(self, value: AttrValue, *, timeout: Timeout = None) -> None: # expect_attr(self.loc, "data-data-type", value=value, timeout=timeout) def expect_time_format(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Asserts that the input element has the expected `data-time-format` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-time-format", value=value, timeout=timeout ) def expect_timezone(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Asserts that the input element has the expected `data-timezone` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-timezone", value=value, timeout=timeout ) def expect_drag_range(self, value: AttrValue, *, timeout: Timeout = None) -> None: + """ + Asserts that the input element has the expected `data-drag-range` attribute value. + + Parameters + ---------- + value : AttrValue + The expected value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-drag-interval", value=value, timeout=timeout ) @@ -1617,6 +2620,18 @@ def should_continue(cur_pxls: float) -> bool: sleep_time = 0.05 def slow_move(x: float, y: float, delay: float = sleep_time) -> None: + """ + Slowly move the mouse to the given coordinates. + + Parameters + ---------- + x : float + The x-coordinate. + y : float + The y-coordinate. + delay : float, optional + The delay between each move, by default sleep_time. + """ mouse.move(x, y) time.sleep(delay) @@ -1685,17 +2700,42 @@ def _handle_center( class InputSlider(_InputSliderBase): + """ Input slider control for :func: `~shiny.ui.input_slider` """ + loc_irs_label: Locator + """ + The locator of the input slider label. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initialize the InputSlider object. + + Parameters + ---------- + page : Page + The Playwright Page object. + id : str + The id of the input element. + """ super().__init__(page, id=id) self.loc_irs_label = self.loc_irs.locator("> .irs > .irs-single") def expect_value(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Asserts that the input element has the expected value. + + Parameters + ---------- + value : PatternOrStr + The expected value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ playwright_expect(self.loc_irs_label).to_have_text(value, timeout=timeout) def set( @@ -1705,6 +2745,19 @@ def set( max_err_values: int = 15, timeout: Timeout = None, ) -> None: + """ + Set the value of the slider. + + Parameters + ---------- + value : str + The value to set the slider to. + max_err_values : int, optional + The maximum number of error values to display if the value is not found. + Defaults to 15. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ self._wait_for_container(timeout=timeout) handle = self.loc_irs.locator("> .irs-handle") @@ -1723,14 +2776,31 @@ def set( class InputSliderRange(_InputSliderBase): + """ Input slider range control for :func: `~shiny.ui.input_slider_range` """ loc_irs_label_from: Locator + """ + The locator of the input slider label for the `from` handle. + """ loc_irs_label_to: Locator + """ + The locator of the input slider label for the `to` handle. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initialize the InputSliderRange object. + + Parameters + ---------- + page : Page + The Playwright Page object. + id : str + The id of the input element. + """ super().__init__(page, id=id) self.loc_irs_label_from = self.loc_irs.locator("> .irs > .irs-from") self.loc_irs_label_to = self.loc_irs.locator("> .irs > .irs-to") @@ -1745,6 +2815,16 @@ def expect_value( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected value. + + Parameters + ---------- + value : Tuple[PatternOrStr, PatternOrStr] + The expected value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ if all_missing(*value): raise ValueError("Both `value` tuple entries cannot be `MISSING_TYPE`") from_val = value[0] @@ -1793,6 +2873,19 @@ def set( max_err_values: int = 15, timeout: Timeout = None, ) -> None: + """ + Set the value of the slider. + + Parameters + ---------- + value : Tuple[str, str] | Tuple[str, MISSING_TYPE] | Tuple[MISSING_TYPE, str] + The value to set the slider to. + max_err_values : int, optional + The maximum number of error values to display if the value is not found. + Defaults to 15. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ if all_missing(*value): raise ValueError("Both `value` tuple entries cannot be `MISSING_TYPE`") @@ -1852,19 +2945,6 @@ class _DateBase( _WidthContainerM, _InputWithLabel, ): - # id: str, - # label: TagChild, - # value: Optional[Union[date, str]] = None, - # min: Optional[Union[date, str]] = None, - # max: Optional[Union[date, str]] = None, - # format: str = "yyyy-mm-dd", - # startview: str = "month", - # weekstart: int = 0, - # language: str = "en", - # width: Optional[str] = None, - # autoclose: bool = True, - # datesdisabled: Optional[list[str]] = None, - # daysofweekdisabled: Optional[list[int]] = None, # Due to the `language` parameter, we can't use `datetime.date` as a value type @@ -1874,6 +2954,16 @@ def expect_value( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected value. + + Parameters + ---------- + value : PatternOrStr + The expected value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ # if value is None: # self.expect.to_be_empty(timeout=timeout) # else: @@ -1885,6 +2975,16 @@ def expect_min_date( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-min-date` attribute value. + + Parameters + ---------- + value : str + The expected `data-min-date` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-min-date", value=value, timeout=timeout ) @@ -1895,6 +2995,16 @@ def expect_max_date( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-max-date` attribute value. + + Parameters + ---------- + value : str + The expected `data-max-date` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-max-date", value=value, timeout=timeout ) @@ -1905,6 +3015,16 @@ def expect_format( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-format` attribute value. + + Parameters + ---------- + value : str + The expected `data-date-format` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-date-format", value=value, timeout=timeout ) @@ -1915,6 +3035,16 @@ def expect_startview( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-start-view` attribute value. + + Parameters + ---------- + value : str + The expected `data-date-start-view` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-date-start-view", value=value, timeout=timeout ) @@ -1925,6 +3055,16 @@ def expect_weekstart( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-week-start` attribute value. + + Parameters + ---------- + value : int + The expected `data-date-week-start` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ if isinstance(value, int): value = str(value) expect_attribute_to_have_value( @@ -1937,6 +3077,16 @@ def expect_language( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-language` attribute value. + + Parameters + ---------- + value : str + The expected `data-date-language` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-date-language", value=value, timeout=timeout ) @@ -1948,6 +3098,16 @@ def expect_autoclose( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-autoclose` attribute value. + + Parameters + ---------- + value : Literal["true", "false"] + The expected `data-date-autoclose` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ expect_attribute_to_have_value( self.loc, "data-date-autoclose", value=value, timeout=timeout ) @@ -1958,6 +3118,16 @@ def expect_datesdisabled( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-dates-disabled` attribute value. + + Parameters + ---------- + value : Optional[list[str]] + The expected `data-date-dates-disabled` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ if isinstance(value, list): assert len(value) > 0, "`value` must be `None` or a non-empty list" value_str = "null" if value is None else json.dumps(value) @@ -1974,6 +3144,16 @@ def expect_daysofweekdisabled( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected `data-date-days-of-week-disabled` attribute value. + + Parameters + ---------- + value : Optional[list[int]] + The expected `data-date-days-of-week-disabled` attribute value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ if isinstance(value, list): assert len(value) > 0, "`value` must be `None` or a non-empty list" value_str = "null" if value is None else json.dumps(value) @@ -1987,6 +3167,16 @@ def expect_daysofweekdisabled( class InputDate(_DateBase): def __init__(self, page: Page, id: str) -> None: + """ + Initialize an InputDate object. + + Parameters + ---------- + page : Page + The page object. + id : str + The id of the input element. + """ super().__init__( page, id=id, @@ -1996,28 +3186,40 @@ def __init__(self, page: Page, id: str) -> None: class InputDateRange(_WidthContainerM, _InputWithLabel): - # id: str, - # label: TagChild, - # *, - # start: Optional[Union[date, str]] = None, - # end: Optional[Union[date, str]] = None, - # min: Optional[Union[date, str]] = None, - # max: Optional[Union[date, str]] = None, - # format: str = "yyyy-mm-dd", - # startview: str = "month", - # weekstart: int = 0, - # language: str = "en", - # separator: str = " to ", - # width: Optional[str] = None, - # autoclose: bool = True, + """ Input date range control for :func: `~shiny.ui.input_date_range` """ loc_separator: Locator + """ + The locator of the separator between the two input elements. + """ loc_start: Locator + """ + The locator of the start date input element. + """ loc_end: Locator + """ + The locator of the end date input element. + """ date_start: _DateBase + """ + The start date input element. + """ date_end: _DateBase + """ + The end date input element. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initialize an InputDateRange object. + + Parameters + ---------- + page : Page + The page object. + id : str + The id of the input element. + """ super().__init__( page, id=id, @@ -2051,6 +3253,16 @@ def set( *, timeout: Timeout = None, ) -> None: + """ + Sets the value of the input element. + + Parameters + ---------- + value : Tuple[str, str] + The value to set. The first element is the start date and the second element is the end date. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to be set. Defaults to None. + """ start = value[0] end = value[1] # TODO-future; Composable set() methods? @@ -2069,6 +3281,16 @@ def expect_value( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected value. + + Parameters + ---------- + value : Tuple[PatternOrStr, PatternOrStr] + The expected value. The first element is the start date and the second element is the end date. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ if all_missing(*value): raise ValueError("Both `start_val` and `end_val` can not be `MISSING_TYPE`") start_val = value[0] @@ -2089,6 +3311,16 @@ def expect_min_date( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected minimum date. + + Parameters + ---------- + value : AttrValue + The expected minimum date. + timeout : Optional[Union[int, float]] + The maximum time to wait for the minimum date to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_min_date(value, timeout=timeout) self.date_end.expect_min_date(value, timeout=timeout) @@ -2100,6 +3332,16 @@ def expect_max_date( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected maximum date. + + Parameters + ---------- + value : AttrValue + The expected maximum date. + timeout : Optional[Union[int, float]] + The maximum time to wait for the maximum date to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_max_date(value, timeout=timeout) self.date_end.expect_max_date(value, timeout=timeout) @@ -2111,6 +3353,16 @@ def expect_format( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected format. + + Parameters + ---------- + value : AttrValue + The expected format. + timeout : Optional[Union[int, float]] + The maximum time to wait for the format to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_format(value, timeout=timeout) self.date_end.expect_format(value, timeout=timeout) @@ -2122,6 +3374,16 @@ def expect_startview( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected start view. + + Parameters + ---------- + value : AttrValue + The expected start view. + timeout : Optional[Union[int, float]] + The maximum time to wait for the start view to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_startview(value, timeout=timeout) self.date_end.expect_startview(value, timeout=timeout) @@ -2133,6 +3395,16 @@ def expect_weekstart( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected week start. + + Parameters + ---------- + value : int + The expected week start. + timeout : Optional[Union[int, float]] + The maximum time to wait for the week start to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_weekstart(value, timeout=timeout) self.date_end.expect_weekstart(value, timeout=timeout) @@ -2144,6 +3416,16 @@ def expect_language( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected language. + + Parameters + ---------- + value : AttrValue + The expected language. + timeout : Optional[Union[int, float]] + The maximum time to wait for the language to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_language(value, timeout=timeout) self.date_end.expect_language(value, timeout=timeout) @@ -2155,6 +3437,16 @@ def expect_separator( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected separator. + + Parameters + ---------- + value : PatternOrStr + The expected separator. + timeout : Optional[Union[int, float]] + The maximum time to wait for the separator to appear. Defaults to None. + """ playwright_expect(self.loc_separator).to_have_text(value, timeout=timeout) # width: Optional[str] = None, @@ -2166,6 +3458,16 @@ def expect_autoclose( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the input element has the expected autoclose value. + + Parameters + ---------- + value : Literal["true", "false"] + The expected autoclose value. + timeout : Optional[Union[int, float]] + The maximum time to wait for the value to appear. Defaults to None. + """ # TODO-future; Composable expectations self.date_start.expect_autoclose(value, timeout=timeout) self.date_end.expect_autoclose(value, timeout=timeout) @@ -2217,6 +3519,16 @@ def expect_value( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the output has the expected value. + + Parameters + ---------- + value + The expected value. + timeout + The maximum time to wait for the value to appear. Defaults to None. + """ """Note this function will trim value and output text value before comparing them""" self.expect.to_have_text(value, timeout=timeout) @@ -2237,6 +3549,16 @@ def expect_container_tag( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the output has the expected container tag. + + Parameters + ---------- + tag_name + The expected container tag. + timeout + The maximum time to wait for the container tag to appear. Defaults to None. + """ loc = self.loc.locator(f"xpath=self::{tag_name}") playwright_expect(loc).to_have_count(1, timeout=timeout) @@ -2245,29 +3567,90 @@ class _OutputInlineContainerM(_OutputContainerM): def expect_inline( self: _OutputContainerP, inline: bool = False, *, timeout: Timeout = None ) -> None: + """ + Asserts that the output is inline. + + Parameters + ---------- + inline + Whether the output is inline. + timeout + The maximum time to wait for the output to appear. Defaults to None. + """ tag_name = "span" if inline else "div" self.expect_container_tag(tag_name, timeout=timeout) class OutputText(_OutputInlineContainerM, _OutputTextValue): + """ Text output control for :func: `~shiny.ui.text_output` """ + + loc: Locator + """ + The locator of the text output. + """ def __init__( self, page: Page, id: str, ) -> None: + """ + Initializes a text output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the text output. + """ super().__init__(page, id=id, loc=f"#{id}.shiny-text-output") def get_value(self, *, timeout: Timeout = None) -> str: + """ + Gets the text value of the output. + + Parameters + ---------- + timeout + The maximum time to wait for the value to appear. Defaults to None. + """ return self.loc.inner_text(timeout=timeout) class OutputCode(_OutputTextValue): + """ Code output control for :func: `~shiny.ui.code_output` """ + + loc: Locator + """ + The locator of the code output. + """ + def __init__(self, page: Page, id: str) -> None: + """ + Initializes a code output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the code output. + """ super().__init__(page, id=id, loc=f"pre#{id}.shiny-text-output") def expect_has_placeholder( self, placeholder: bool = False, *, timeout: Timeout = None ) -> None: + """ + Asserts that the code output has the expected placeholder. + + Parameters + ---------- + placeholder + Whether the code output has a placeholder. + timeout + The maximum time to wait for the placeholder to appear. Defaults to None. + """ _expect_class_value( self.loc, cls="noplaceholder", @@ -2277,7 +3660,23 @@ def expect_has_placeholder( class OutputTextVerbatim(_OutputTextValue): + """ Verbatim text output control for :func: `~shiny.ui.text_output_verbatim` """ + + loc: Locator + """ + The locator of the verbatim text output. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a verbatim text output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the verbatim text output. + """ super().__init__(page, id=id, loc=f"pre#{id}.shiny-text-output") def expect_has_placeholder( @@ -2292,14 +3691,25 @@ def expect_has_placeholder( class _OutputImageBase(_OutputInlineContainerM, _OutputBase): - # id: str - # width: str = "100%" - # height: str = "400px" - # inline: bool = False loc_img: Locator + """ + The locator of the image. + """ def __init__(self, page: Page, id: str, loc_classes: str = "") -> None: + """ + Initializes an image output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the image. + loc_classes + Additional classes to locate the image. Defaults to "". + """ super().__init__( page, id=id, @@ -2313,6 +3723,16 @@ def expect_height( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the image has the expected height. + + Parameters + ---------- + value + The expected height. + timeout + The maximum time to wait for the height to appear. Defaults to None. + """ expect_to_have_style(self.loc, "height", value, timeout=timeout) def expect_width( @@ -2321,6 +3741,16 @@ def expect_width( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the image has the expected width. + + Parameters + ---------- + value + The expected width. + timeout + The maximum time to wait for the width to appear. Defaults to None. + """ expect_to_have_style(self.loc, "width", value, timeout=timeout) def expect_img_src( @@ -2329,6 +3759,16 @@ def expect_img_src( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the image has the expected src. + + Parameters + ---------- + value + The expected src. + timeout + The maximum time to wait for the src to appear. Defaults to None. + """ expect_attribute_to_have_value(self.loc_img, "src", value, timeout=timeout) def expect_img_width( @@ -2337,6 +3777,16 @@ def expect_img_width( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the image has the expected width. + + Parameters + ---------- + value + The expected width. + timeout + The maximum time to wait for the width to appear. Defaults to None. + """ expect_attribute_to_have_value(self.loc_img, "width", value, timeout=timeout) def expect_img_height( @@ -2345,6 +3795,16 @@ def expect_img_height( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the image has the expected height. + + Parameters + ---------- + value + The expected height. + timeout + The maximum time to wait for the height to appear. Defaults to None. + """ expect_attribute_to_have_value(self.loc_img, "height", value, timeout=timeout) def expect_img_alt( @@ -2353,6 +3813,16 @@ def expect_img_alt( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the image has the expected alt text. + + Parameters + ---------- + value + The expected alt text. + timeout + The maximum time to wait for the alt text to appear. Defaults to None. + """ expect_attribute_to_have_value(self.loc_img, "alt", value, timeout=timeout) # def expect_img_style( @@ -2366,24 +3836,58 @@ def expect_img_alt( class OutputImage(_OutputImageBase): def __init__(self, page: Page, id: str) -> None: + """ + Initializes an image output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the image. + """ super().__init__(page, id=id) class OutputPlot(_OutputImageBase): - # shiny-plot-output - # id: str - # width: str = "100%" - # height: str = "400px" - # inline: bool = False + """ Plot output control for :func: `~shiny.ui.plot_output` """ + + loc: Locator + """ + The locator of the plot output. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a plot output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the plot. + """ super().__init__(page, id=id, loc_classes=".shiny-plot-output") class OutputUi(_OutputInlineContainerM, _OutputBase): - # id: str, - # inline: bool = False, - # container: Optional[TagFunction] = None, + """ UI output control for :func: `~shiny.ui.ui_output` """ + + loc: Locator + """ + The locator of the UI output. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a UI output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the UI output. + """ super().__init__(page, id=id, loc=f"#{id}") # TODO-future; Should we try verify that `recalculating` class is not present? Do this for all outputs! @@ -2399,9 +3903,24 @@ def expect_text(self, text: str, *, timeout: Timeout = None) -> None: # When making selectors, use `xpath` so that direct decendents can be checked class OutputTable(_OutputBase): - # id: str, - # **kwargs: TagAttrArg + + """ Table output control for :func: `~shiny.ui.table_output` """ + + loc: Locator + """ + The locator of the table output. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a table output. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the table. + """ super().__init__(page, id=id, loc=f"#{id}") def expect_cell( @@ -2412,6 +3931,20 @@ def expect_cell( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the table cell has the expected text. + + Parameters + ---------- + text + The expected text in the cell. + row + The row number. + col + The column number. + timeout + The maximum time to wait for the text to appear. Defaults to None. + """ assert_type(row, int) assert_type(col, int) playwright_expect( @@ -2426,6 +3959,16 @@ def expect_column_labels( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the table has the expected column labels. + + Parameters + ---------- + labels + The expected column labels. If None, it asserts that the table has no column labels. + timeout + The maximum time to wait for the column labels to appear. Defaults to None. + """ if isinstance(labels, list) and len(labels) == 0: labels = None @@ -2446,6 +3989,18 @@ def expect_column_text( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the column has the expected text. + + Parameters + ---------- + col + The column number. + text + The expected text in the column. + timeout + The maximum time to wait for the text to appear. Defaults to None. + """ assert_type(col, int) playwright_expect( self.loc.locator(f"xpath=./table/tbody/tr/td[{col}]") @@ -2460,6 +4015,16 @@ def expect_n_col( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the table has the expected number of columns. + + Parameters + ---------- + n + The expected number of columns in the table. + timeout + The maximum time to wait for the table to have the expected number of columns. Defaults to None. + """ playwright_expect( # self.loc.locator("xpath=./table/thead/tr[1]/(td|th)") self.loc.locator("xpath=./table/thead/tr[1]/td | ./table/thead/tr[1]/th") @@ -2474,6 +4039,16 @@ def expect_n_row( *, timeout: Timeout = None, ) -> None: + """ + Asserts that the table has the expected number of rows. + + Parameters + ---------- + n + The expected number of rows in the table. + timeout + The maximum time to wait for the table to have the expected number of rows. Defaults to None. + """ playwright_expect(self.loc.locator("xpath=./table/tbody/tr")).to_have_count( n, timeout=timeout, @@ -2484,17 +4059,35 @@ class Sidebar( _WidthLocM, _InputWithContainer, ): - # *args: TagChild | TagAttrs, - # width: CssUnit = 250, - # position: Literal["left", "right"] = "left", - # open: Literal["desktop", "open", "closed", "always"] = "desktop", - # id: Optional[str] = None, - # title: TagChild | str = None, - # bg: Optional[str] = None, - # fg: Optional[str] = None, - # class_: Optional[str] = None, # TODO-future; Consider using `**kwargs` instead - # max_height_mobile: Optional[str | float] = None, + """ Sidebar control for func: `~shiny.ui.sidebar` """ + loc_container: Locator + """ + `loc_container` is the locator of the container of the input. + """ + loc: Locator + """ + The locator for the sidebar. + """ + loc_handle: Locator + """ + The locator for the handle of the sidebar. + """ + loc_position: Locator + """ + The locator for the position of the sidebar. + """ + def __init__(self, page: Page, id: str) -> None: + """ + Initializes a sidebar control. + + Parameters + ---------- + page + The Playwright page. + id + The ID of the sidebar. + """ super().__init__( page, id=id, @@ -2505,11 +4098,31 @@ def __init__(self, page: Page, id: str) -> None: self.loc_position = self.loc.locator("..") def expect_text(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Asserts that the sidebar has the expected text. + + Parameters + ---------- + value + The expected text in the sidebar. + timeout + The maximum time to wait for the text to appear. Defaults to None. + """ playwright_expect(self.loc).to_have_text(value, timeout=timeout) def expect_position( self, position: Literal["left", "right"], *, timeout: Timeout = None ) -> None: + """ + Asserts that the sidebar is in the expected position. + + Parameters + ---------- + position + The expected position of the sidebar. + timeout + The maximum time to wait for the sidebar to appear. Defaults to None. + """ is_right_sidebar = position == "right" _expect_class_value( self.loc_position, @@ -2519,18 +4132,56 @@ def expect_position( ) def expect_handle(self, exists: bool, *, timeout: Timeout = None) -> None: + """ + Asserts that the sidebar handle exists or does not exist. + + Parameters + ---------- + exists + True if the sidebar handle should exist, False otherwise. + timeout + The maximum time to wait for the sidebar handle to appear. Defaults to None. + """ playwright_expect(self.loc_handle).to_have_count(int(exists), timeout=timeout) def expect_open(self, open: bool, *, timeout: Timeout = None) -> None: + """ + Expect the sidebar to be open or closed. + + Parameters + ---------- + open + True if the sidebar should be open, False otherwise. + timeout + The maximum time to wait for the sidebar to open or close. Defaults to None. + """ playwright_expect(self.loc_handle).to_have_attribute( "aria-expanded", str(open).lower(), timeout=timeout ) def set(self, open: bool, *, timeout: Timeout = None) -> None: + """ + Sets the sidebar to be open or closed. + + Parameters + ---------- + open + True if the sidebar should be open, False otherwise. + timeout + The maximum time to wait for the sidebar to open or close. Defaults to None. + """ if open ^ (self.loc_handle.get_attribute("aria-expanded") == "true"): self.toggle(timeout=timeout) def toggle(self, *, timeout: Timeout = None) -> None: + """ + Toggles the sidebar open or closed. + + Parameters + ---------- + timeout + The maximum time to wait for the sidebar to toggle. Defaults to None. + """ self.loc_handle.wait_for(state="visible", timeout=timeout) self.loc_handle.scroll_into_view_if_needed(timeout=timeout) self.loc_handle.click(timeout=timeout) @@ -2992,15 +4643,32 @@ class Accordion( _WidthLocM, _InputWithContainer, ): - # *args: AccordionPanel | TagAttrs, - # id: Optional[str] = None, - # open: Optional[bool | str | list[str]] = None, - # multiple: bool = True, - # class_: Optional[str] = None, - # width: Optional[CssUnit] = None, - # height: Optional[CssUnit] = None, - # **kwargs: TagAttrValue, + """ Accordion control for :func:`~shiny.ui.accordion` """ + + loc: Locator + """ + `Locator` for the accordion + """ + loc_container: Locator + """ + `Locator` for the accordion container + """ + loc_open: Locator + """ + `Locator` for the open accordion panel + """ + def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the Accordion class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the accordion. + """ super().__init__( page, id=id, @@ -3017,9 +4685,29 @@ def __init__(self, page: Page, id: str) -> None: ) def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: + """ + Expects the accordion to have the specified height. + + Parameters + ---------- + value + The expected height. + timeout + The maximum time to wait for the height to be visible and interactable. Defaults to None. + """ expect_to_have_style(self.loc_container, "height", value, timeout=timeout) def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: + """ + Expects the accordion to have the specified width. + + Parameters + ---------- + value + The expected width. + timeout + The maximum time to wait for the width to be visible and interactable. Defaults to None. + """ expect_to_have_style(self.loc_container, "width", value, timeout=timeout) def expect_open( @@ -3048,6 +4736,16 @@ def expect_panels( *, timeout: Timeout = None, ) -> None: + """ + Expects the accordion to have the specified panels. + + Parameters + ---------- + value + The expected panels. + timeout + The maximum time to wait for the panels to be visible and interactable. Defaults to None. + """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, loc_container=self.loc_container, @@ -3064,6 +4762,16 @@ def set( *, timeout: Timeout = None, ) -> None: + """ + Sets the state of the accordion panel. + + Parameters + ---------- + selected + The selected accordion panel(s). + timeout + The maximum time to wait for the accordion panel to be visible and interactable. Defaults to None. + """ if isinstance(selected, str): selected = [selected] for element in self.loc.element_handles(): @@ -3082,6 +4790,14 @@ def accordion_panel( self, data_value: str, ) -> AccordionPanel: + """ + Returns the accordion panel with the specified data value. + + Parameters + ---------- + data_value + The data value of the accordion panel. + """ return AccordionPanel(self.page, self.id, data_value) @@ -3089,14 +4805,43 @@ class AccordionPanel( _WidthLocM, _InputWithContainer, ): - # self, - # *args: TagChild | TagAttrs, - # data_value: str, - # icon: TagChild | None, - # title: TagChild | None, - # id: str | None, - # **kwargs: TagAttrValue, + """ + AccordionPanel control for :func:`~shiny.ui.accordion_panel` + """ + + loc_label: Locator + """ + `Locator` for the accordion panel label + """ + loc_icon: Locator + """ + `Locator` for the accordion panel icon + """ + loc_body: Locator + """ + `Locator` for the accordion panel body + """ + loc_header: Locator + """ + `Locator` for the accordion panel header + """ + loc_body_visible: Locator + """ + `Locator` for the visible accordion panel body + """ def __init__(self, page: Page, id: str, data_value: str) -> None: + """ + Initializes a new instance of the AccordionPanel class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the accordion panel. + data_value + The data value of the accordion panel. + """ super().__init__( page, id=id, @@ -3117,19 +4862,69 @@ def __init__(self, page: Page, id: str, data_value: str) -> None: self.loc_body_visible = self.loc.locator("> .accordion-collapse.show") def expect_label(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the accordion panel label to have the specified text. + + Parameters + ---------- + value + The expected text pattern or string. + timeout + The maximum time to wait for the label to appear. Defaults to None. + """ playwright_expect(self.loc_label).to_have_text(value, timeout=timeout) def expect_body(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the accordion panel body to have the specified text. + + Parameters + ---------- + value + The expected text pattern or string. + timeout + The maximum time to wait for the body to appear. Defaults to None. + """ playwright_expect(self.loc_body).to_have_text(value, timeout=timeout) def expect_icon(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the accordion panel icon to have the specified text. + + Parameters + ---------- + value + The expected text pattern or string. + timeout + The maximum time to wait for the icon to appear. Defaults to None. + """ playwright_expect(self.loc_icon).to_have_text(value, timeout=timeout) def expect_open(self, is_open: bool, *, timeout: Timeout = None) -> None: + """ + Expects the accordion panel to be open or closed. + + Parameters + ---------- + is_open + True if the accordion panel is expected to be open, False otherwise. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ _expect_class_value(self.loc_body, "show", is_open, timeout=timeout) # user sends value of Open: true | false def set(self, open: bool, *, timeout: Timeout = None) -> None: + """ + Sets the state of the control to open or closed. + + Parameters + ---------- + open + True if the control is expected to be open, False otherwise. + timeout + The maximum time to wait for the control to be visible and interactable. Defaults to None. + """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) expect_not_to_have_class(self.loc_body, "collapsing", timeout=timeout) @@ -3137,12 +4932,33 @@ def set(self, open: bool, *, timeout: Timeout = None) -> None: self.toggle(timeout=timeout) def toggle(self, *, timeout: Timeout = None) -> None: + """ + Toggles the state of the control. + + Parameters + ---------- + timeout + The maximum time to wait for the control to be visible and interactable. Defaults to None. + """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) self.loc_header.click(timeout=timeout) class _OverlayBase(_InputBase): + """ Base class for overlay controls """ + loc_trigger: Locator + """ + `loc_trigger` is the locator of the trigger element. + """ + loc_overlay_body: Locator + """ + `loc_overlay_body` is the locator of the overlay body. + """ + loc_overlay_container: Locator + """ + `loc_overlay_container` is the locator of the overlay container. + """ def __init__( self, page: Page, @@ -3152,6 +4968,22 @@ def __init__( overlay_name: str, overlay_selector: str, ) -> None: + """ + Initializes a new instance of the OverlayBase class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the overlay. + loc + The locator of the overlay. + overlay_name + The name of the overlay. + overlay_selector + The selector of the overlay. + """ super().__init__(page, id=id, loc=loc) self._overlay_name = overlay_name self._overlay_selector = overlay_selector @@ -3186,14 +5018,42 @@ def get_loc_overlay_body(self, *, timeout: Timeout = None) -> Locator: ) def get_loc_overlay_container(self, *, timeout: Timeout = None) -> Locator: + """ + Returns the locator for the overlay container. + + Parameters + ---------- + timeout + The maximum time to wait for the overlay container to appear. Defaults to None. + """ return self.page.locator(f"#{self._get_overlay_id(timeout=timeout)}") def expect_body(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the overlay body to have the specified text. + + Parameters + ---------- + value + The expected text pattern or string. + timeout + The maximum time to wait for the overlay body to appear. Defaults to None. + """ playwright_expect(self.get_loc_overlay_body(timeout=timeout)).to_have_text( value, timeout=timeout ) def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: + """ + Expects the overlay to be active or inactive. + + Parameters + ---------- + active + True if the overlay is expected to be active, False otherwise. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ value = re.compile(r".*") if active else None return expect_attribute_to_have_value( loc=self.loc_trigger, @@ -3203,6 +5063,16 @@ def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: ) def expect_placement(self, value: str, *, timeout: Timeout = None) -> None: + """ + Expects the overlay to have the specified placement. + + Parameters + ---------- + value + The expected placement value. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ return expect_attribute_to_have_value( loc=self.get_loc_overlay_container(timeout=timeout), timeout=timeout, @@ -3212,14 +5082,30 @@ def expect_placement(self, value: str, *, timeout: Timeout = None) -> None: class Popover(_OverlayBase): - # trigger: TagChild, - # *args: TagChild | TagAttrs, - # title: Optional[TagChild] = None, - # id: Optional[str] = None, - # placement: Literal["auto", "top", "right", "bottom", "left"] = "auto", - # options: Optional[dict[str, Any]] = None, - # **kwargs: TagAttrValue, + """ Popover control for :func:`~shiny.ui.popover` """ + loc_trigger: Locator + """ + `loc_trigger` is the locator of the trigger element. + """ + loc_overlay_body: Locator + """ + `loc_overlay_body` is the locator of the overlay body. + """ + loc_overlay_container: Locator + """ + `loc_overlay_container` is the locator of the overlay container. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the Popover class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the popover. + """ super().__init__( page, id=id, @@ -3229,23 +5115,66 @@ def __init__(self, page: Page, id: str) -> None: ) def set(self, open: bool, timeout: Timeout = None) -> None: + """ + Sets the state of the popover. + + Parameters + ---------- + open + True if the popover is expected to be open, False otherwise. + timeout + The maximum time to wait for the popover to be visible and interactable. Defaults to None. + """ if open ^ self.get_loc_overlay_body(timeout=timeout).count() > 0: self.toggle() def toggle(self, timeout: Timeout = None) -> None: + """ + Toggles the state of the popover. + + Parameters + ---------- + timeout + The maximum time to wait for the popover to be visible and interactable. Defaults to None. + """ self.loc_trigger.wait_for(state="visible", timeout=timeout) self.loc_trigger.scroll_into_view_if_needed(timeout=timeout) self.loc_trigger.click(timeout=timeout) class Tooltip(_OverlayBase): - # trigger: TagChild, - # *args: TagChild | TagAttrs, - # id: Optional[str] = None, - # placement: Literal["auto", "top", "right", "bottom", "left"] = "auto", - # options: Optional[dict[str, object]] = None, - # **kwargs: TagAttrValue, + """ Tooltip control for :func:`~shiny.ui.tooltip` """ + loc_container: Locator + """ + `loc_container` is the locator of the container of the input. + """ + loc: Locator + """ + `loc` is the locator of the input. + """ + loc_trigger: Locator + """ + `loc_trigger` is the locator of the trigger element. + """ + loc_overlay_body: Locator + """ + `loc_overlay_body` is the locator of the overlay body. + """ + loc_overlay_container: Locator + """ + `loc_overlay_container` is the locator of the overlay container. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the Tooltip class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the tooltip. + """ super().__init__( page, id=id, @@ -3255,18 +5184,37 @@ def __init__(self, page: Page, id: str) -> None: ) def set(self, open: bool, timeout: Timeout = None) -> None: + """ + Sets the state of the tooltip. + + Parameters + ---------- + open + True if the tooltip is expected to be open, False otherwise. + timeout + The maximum time to wait for the tooltip to be visible and interactable. Defaults to None. + """ if open ^ self.get_loc_overlay_body(timeout=timeout).count() > 0: self.toggle(timeout=timeout) if not open: self.get_loc_overlay_body(timeout=timeout).click() def toggle(self, timeout: Timeout = None) -> None: + """ + Toggles the state of the tooltip. + + Parameters + ---------- + timeout + The maximum time to wait for the tooltip to be visible and interactable. Defaults to None. + """ self.loc_trigger.wait_for(state="visible", timeout=timeout) self.loc_trigger.scroll_into_view_if_needed(timeout=timeout) self.loc_trigger.hover(timeout=timeout) class _NavItemBase(_InputWithContainer): + """ A Base mixin class for Nav and NavItem controls """ def nav_item( self, value: str, @@ -3274,9 +5222,27 @@ def nav_item( return NavItem(self.page, self.id, value) def set(self, value: str, *, timeout: Timeout = None) -> None: + """ + Sets the state of the control to open or closed. + + Parameters + ---------- + value + The selected nav item. + """ self.nav_item(value).click(timeout=timeout) def expect_value(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the control to have the specified value. + + Parameters + ---------- + value + The expected value. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ # data attribute of active tab and compare with value playwright_expect( self.loc_container.locator('a[role="tab"].active') @@ -3292,12 +5258,30 @@ def expect_value(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: # ) def get_loc_active_content(self, *, timeout: Timeout = None) -> Locator: + """ + Returns the locator for the active content. + + Parameters + ---------- + timeout + The maximum time to wait for the locator to appear. Defaults to None. + """ datatab_id = self.loc_container.get_attribute("data-tabsetid", timeout=timeout) return self.page.locator( f"div.tab-content[data-tabsetid='{datatab_id}'] > div.tab-pane.active" ) def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the control to have the specified content. + + Parameters + ---------- + value + The expected content. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ playwright_expect(self.get_loc_active_content()).to_have_text( value, timeout=timeout ) @@ -3308,6 +5292,16 @@ def expect_nav_values( *, timeout: Timeout = None, ) -> None: + """ + Expects the control to have the specified nav values. + + Parameters + ---------- + value + The expected nav values. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, loc_container=self.loc_container, @@ -3324,16 +5318,46 @@ def expect_nav_titles( *, timeout: Timeout = None, ) -> None: + """ + Expects the control to have the specified nav titles. + + Parameters + ---------- + value + The expected nav titles. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ self.expect.to_have_text(value, timeout=timeout) class NavItem(_InputWithContainer): - # *args: NavsetArg, - # id: Optional[str] = None, - # selected: Optional[str] = None, - # header: TagChild = None, - # footer: TagChild = None, + """ NavItem control for :func:`~shiny.ui.nav_item` """ + + """ + `Locator` for the content of the nav item. + """ + loc: Locator + """ + `Locator` for the nav item. + """ + loc_container: Locator + """ + `Locator` for the nav item container. + """ def __init__(self, page: Page, id: str, data_value: str) -> None: + """ + Initializes a new instance of the NavItem class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav item. + data_value + The data value of the nav item. + """ super().__init__( page, id=id, @@ -3347,6 +5371,7 @@ def __init__(self, page: Page, id: str, data_value: str) -> None: # get active content instead of assertion @property def loc_content(self) -> Locator: + """Returns the locator for the content of the nav item.""" """Note. This requires 2 steps. Will not work if the overlay element is rapidly created during locator fetch""" datatab_id = self.loc_container.get_attribute("data-tabsetid") return self.page.locator( @@ -3354,22 +5379,65 @@ def loc_content(self) -> Locator: ) def click(self, *, timeout: Timeout = None) -> None: + """ + Clicks the nav item. + + Parameters + ---------- + timeout + The maximum time to wait for the nav item to be visible and interactable. Defaults to None. + """ self.loc.click(timeout=timeout) def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: + """ + Expects the nav item to be active or inactive. + + Parameters + ---------- + active + True if the nav item is expected to be active, False otherwise. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ _expect_class_value(self.loc, "active", active, timeout=timeout) def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: + """ + Expects the nav item content to have the specified text. + + Parameters + ---------- + value + The expected text pattern or string. + timeout + The maximum time to wait for the expectation to pass. Defaults to None. + """ playwright_expect(self.loc_content).to_have_text(value, timeout=timeout) class NavsetTab(_NavItemBase): - # *args: NavsetArg, - # id: Optional[str] = None, - # selected: Optional[str] = None, - # header: TagChild = None, - # footer: TagChild = None, + """ NavsetTab control for :func:`~shiny.ui.navset_tab` """ + + loc: Locator + """ + `Locator` for the nav set tab. + """ + loc_container: Locator + """ + `Locator` for the nav set tab container. + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetTab class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set tab. + """ super().__init__( page, id=id, @@ -3379,7 +5447,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetPill(_NavItemBase): + """ NavsetPill control for :func:`~shiny.ui.navset_pill` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetPill class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set pill. + """ super().__init__( page, id=id, @@ -3389,7 +5468,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetUnderline(_NavItemBase): + """ NavsetUnderline control for :func:`~shiny.ui.navset_underline` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetUnderline class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set underline. + """ super().__init__( page, id=id, @@ -3399,7 +5489,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetPillList(_NavItemBase): + """ NavsetPillList control for :func:`~shiny.ui.navset_pill_list` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetPillList class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set pill list. + """ super().__init__( page, id=id, @@ -3409,7 +5510,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardTab(_NavItemBase): + """ NavsetCardTab control for :func:`~shiny.ui.navset_card_tab` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetCardTab class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set card tab. + """ super().__init__( page, id=id, @@ -3419,7 +5531,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardPill(_NavItemBase): + """ NavsetCardPill control for :func:`~shiny.ui.navset_card_pill` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetCardPill class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set card pill. + """ super().__init__( page, id=id, @@ -3429,7 +5552,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardUnderline(_NavItemBase): + """ NavsetCardUnderline control for :func:`~shiny.ui.navset_card_underline` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetCardUnderline class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set card underline. + """ super().__init__( page, id=id, @@ -3439,7 +5573,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetHidden(_NavItemBase): + """ NavsetHidden control for :func:`~shiny.ui.navset_hidden` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetHidden class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set hidden. + """ super().__init__( page, id=id, @@ -3449,7 +5594,18 @@ def __init__(self, page: Page, id: str) -> None: class NavsetBar(_NavItemBase): + """ NavsetBar control for :func:`~shiny.ui.navset_bar` """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the NavsetBar class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the nav set bar. + """ super().__init__( page, id=id, @@ -3907,7 +6063,6 @@ def expect_cell_title( timeout The maximum time to wait for the expectation to pass. Defaults to None. """ - playwright_expect(self.cell_locator(row=row, col=col)).to_have_attribute( name="title", value=message, timeout=timeout ) @@ -3915,7 +6070,20 @@ def expect_cell_title( # TODO: Use mixin for dowloadlink and download button class DownloadLink(_InputActionBase): + """ + DownloadLink control for :func:`~shiny.ui.download_link` + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the DownloadLink class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the download link. + """ super().__init__( page, id=id, @@ -3927,7 +6095,20 @@ class DownloadButton( _WidthLocM, _InputActionBase, ): + """ + DownloadButton control for :func:`~shiny.ui.download_button` + """ def __init__(self, page: Page, id: str) -> None: + """ + Initializes a new instance of the DownloadButton class. + + Parameters + ---------- + page + The Playwright page object. + id + The ID of the download button. + """ super().__init__( page, id=id, From df9ae71a05273779db98fb1efc36bcb555e0dd95 Mon Sep 17 00:00:00 2001 From: Karan Gathani Date: Thu, 6 Jun 2024 11:08:42 -0700 Subject: [PATCH 02/11] Address formatting issues --- shiny/playwright/controls/_controls.py | 128 ++++++++++++++++--------- 1 file changed, 84 insertions(+), 44 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index 387fd9a5d..7ab20276a 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -149,7 +149,7 @@ class _InputBaseP(Protocol): class _InputWithContainerP(_InputBaseP, Protocol): - """ A mixin class representing inputs with a container. """ + """A mixin class representing inputs with a container.""" loc_container: Locator """ @@ -158,7 +158,8 @@ class _InputWithContainerP(_InputBaseP, Protocol): class _InputBase: - """ A base class representing inputs. """ + """A base class representing inputs.""" + # timeout: Timeout id: str loc: Locator @@ -248,7 +249,7 @@ def __init__( class _InputWithLabel(_InputWithContainer): - """ A mixin class representing inputs with a label. """ + """A mixin class representing inputs with a label.""" loc: Locator """ @@ -393,7 +394,8 @@ def set(self: _InputBaseP, value: str, *, timeout: Timeout = None) -> None: class _ExpectTextInputValueM: - """ A mixin class representing text input values. """ + """A mixin class representing text input values.""" + def expect_value( self: _InputBaseP, value: PatternOrStr, @@ -420,7 +422,8 @@ class InputNumeric( _WidthLocM, _InputWithLabel, ): - """ Input numeric control for :func: `~shiny.ui.input_numeric` """ + """Input numeric control for :func: `~shiny.ui.input_numeric`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes the input numeric. @@ -575,7 +578,7 @@ class InputText( _ExpectSpellcheckAttrM, _InputWithLabel, ): - """ Input text control for :func: `~shiny.ui.input_text` """ + """Input text control for :func: `~shiny.ui.input_text`""" loc: Locator """ @@ -589,6 +592,7 @@ class InputText( """ The locator of the label of the input. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes the input text. @@ -613,7 +617,7 @@ class InputPassword( _ExpectPlaceholderAttrM, _InputWithLabel, ): - """ Input password control for :func: `~shiny.ui.input_password` """ + """Input password control for :func: `~shiny.ui.input_password`""" loc: Locator """ @@ -671,12 +675,13 @@ class InputTextArea( _ExpectSpellcheckAttrM, _InputWithLabel, ): - """ Input text area control for :func: `~shiny.ui.input_text_area` """ + """Input text area control for :func: `~shiny.ui.input_text_area`""" loc: Locator """ The locator of the input. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes the input text area. @@ -1030,7 +1035,8 @@ def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: class InputSelect(_InputSelectBase): - """ Input select control for :func: `~shiny.ui.input_select` """ + """Input select control for :func: `~shiny.ui.input_select`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes the input select. @@ -1071,7 +1077,8 @@ def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: class InputSelectize(_InputSelectBase): - """ Input selectize control for :func: `~shiny.ui.input_selectize` """ + """Input selectize control for :func: `~shiny.ui.input_selectize`""" + def __init__(self, page: Page, id: str) -> None: super().__init__( page, @@ -1108,7 +1115,8 @@ class InputActionButton( _WidthLocM, _InputActionBase, ): - """ Input action button control for :func: `~shiny.ui.input_action_button` """ + """Input action button control for :func: `~shiny.ui.input_action_button`""" + def __init__( self, page: Page, @@ -1132,7 +1140,8 @@ def __init__( class InputDarkMode(_InputBase): - """ Input dark mode control for :func: `~shiny.ui.input_dark_mode` """ + """Input dark mode control for :func: `~shiny.ui.input_dark_mode`""" + def __init__( self, page: Page, @@ -1224,12 +1233,13 @@ class InputTaskButton( _WidthLocM, _InputActionBase, ): - """ Input task button control for :func: `~shiny.ui.input_task_button` """ + """Input task button control for :func: `~shiny.ui.input_task_button`""" loc: Locator """ The locator of the input task button. """ + # TODO-Karan: Test auto_reset functionality def __init__( self, @@ -1356,12 +1366,13 @@ def expect_auto_reset(self, value: bool, timeout: Timeout = None): class InputActionLink(_InputActionBase): - """ Input action link control for :func: `~shiny.ui.input_action_link` """ + """Input action link control for :func: `~shiny.ui.input_action_link`""" loc: Locator """ The locator of the input action link. """ + def __init__( self, page: Page, @@ -1468,7 +1479,7 @@ def expect_checked(self, value: bool, *, timeout: Timeout = None) -> None: class InputCheckbox(_InputCheckboxBase): - """ Input checkbox control for :func: `~shiny.ui.input_checkbox` """ + """Input checkbox control for :func: `~shiny.ui.input_checkbox`""" loc: Locator """ @@ -1482,6 +1493,7 @@ class InputCheckbox(_InputCheckboxBase): """ The locator of the label of the input checkbox. """ + def __init__( self, page: Page, @@ -1506,7 +1518,7 @@ def __init__( class InputSwitch(_InputCheckboxBase): - """ Input switch control for :func: `~shiny.ui.input_switch` """ + """Input switch control for :func: `~shiny.ui.input_switch`""" loc: Locator """ @@ -1520,6 +1532,7 @@ class InputSwitch(_InputCheckboxBase): """ The locator of the label of the input switch. """ + def __init__( self, page: Page, @@ -1981,7 +1994,7 @@ class InputRadioButtons( _WidthContainerM, _RadioButtonCheckboxGroupBase, ): - """ Input radio buttons control for :func: `~shiny.ui.input_radio_buttons` """ + """Input radio buttons control for :func: `~shiny.ui.input_radio_buttons`""" loc_selected: Locator """ @@ -1995,6 +2008,7 @@ class InputRadioButtons( """ The locator of the labels of the radio button choices. """ + def __init__( self, page: Page, @@ -2113,7 +2127,7 @@ class InputFile( # _ExpectPlaceholderAttrM, _InputWithLabel, ): - """ Input file control for :func: `~shiny.ui.input_file` """ + """Input file control for :func: `~shiny.ui.input_file`""" loc_button: Locator """ @@ -2700,7 +2714,7 @@ def _handle_center( class InputSlider(_InputSliderBase): - """ Input slider control for :func: `~shiny.ui.input_slider` """ + """Input slider control for :func: `~shiny.ui.input_slider`""" loc_irs_label: Locator """ @@ -2776,7 +2790,8 @@ def set( class InputSliderRange(_InputSliderBase): - """ Input slider range control for :func: `~shiny.ui.input_slider_range` """ + """Input slider range control for :func: `~shiny.ui.input_slider_range`""" + loc_irs_label_from: Locator """ The locator of the input slider label for the `from` handle. @@ -3186,7 +3201,7 @@ def __init__(self, page: Page, id: str) -> None: class InputDateRange(_WidthContainerM, _InputWithLabel): - """ Input date range control for :func: `~shiny.ui.input_date_range` """ + """Input date range control for :func: `~shiny.ui.input_date_range`""" loc_separator: Locator """ @@ -3582,12 +3597,13 @@ def expect_inline( class OutputText(_OutputInlineContainerM, _OutputTextValue): - """ Text output control for :func: `~shiny.ui.text_output` """ + """Text output control for :func: `~shiny.ui.text_output`""" loc: Locator """ The locator of the text output. """ + def __init__( self, page: Page, @@ -3618,7 +3634,7 @@ def get_value(self, *, timeout: Timeout = None) -> str: class OutputCode(_OutputTextValue): - """ Code output control for :func: `~shiny.ui.code_output` """ + """Code output control for :func: `~shiny.ui.code_output`""" loc: Locator """ @@ -3660,12 +3676,13 @@ def expect_has_placeholder( class OutputTextVerbatim(_OutputTextValue): - """ Verbatim text output control for :func: `~shiny.ui.text_output_verbatim` """ + """Verbatim text output control for :func: `~shiny.ui.text_output_verbatim`""" loc: Locator """ The locator of the verbatim text output. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a verbatim text output. @@ -3850,12 +3867,13 @@ def __init__(self, page: Page, id: str) -> None: class OutputPlot(_OutputImageBase): - """ Plot output control for :func: `~shiny.ui.plot_output` """ + """Plot output control for :func: `~shiny.ui.plot_output`""" loc: Locator """ The locator of the plot output. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a plot output. @@ -3871,12 +3889,13 @@ def __init__(self, page: Page, id: str) -> None: class OutputUi(_OutputInlineContainerM, _OutputBase): - """ UI output control for :func: `~shiny.ui.ui_output` """ + """UI output control for :func: `~shiny.ui.ui_output`""" loc: Locator """ The locator of the UI output. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a UI output. @@ -3903,13 +3922,13 @@ def expect_text(self, text: str, *, timeout: Timeout = None) -> None: # When making selectors, use `xpath` so that direct decendents can be checked class OutputTable(_OutputBase): - - """ Table output control for :func: `~shiny.ui.table_output` """ + """Table output control for :func: `~shiny.ui.table_output`""" loc: Locator """ The locator of the table output. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a table output. @@ -4059,7 +4078,8 @@ class Sidebar( _WidthLocM, _InputWithContainer, ): - """ Sidebar control for func: `~shiny.ui.sidebar` """ + """Sidebar control for func: `~shiny.ui.sidebar`""" + loc_container: Locator """ `loc_container` is the locator of the container of the input. @@ -4643,7 +4663,7 @@ class Accordion( _WidthLocM, _InputWithContainer, ): - """ Accordion control for :func:`~shiny.ui.accordion` """ + """Accordion control for :func:`~shiny.ui.accordion`""" loc: Locator """ @@ -4829,6 +4849,7 @@ class AccordionPanel( """ `Locator` for the visible accordion panel body """ + def __init__(self, page: Page, id: str, data_value: str) -> None: """ Initializes a new instance of the AccordionPanel class. @@ -4946,7 +4967,8 @@ def toggle(self, *, timeout: Timeout = None) -> None: class _OverlayBase(_InputBase): - """ Base class for overlay controls """ + """Base class for overlay controls""" + loc_trigger: Locator """ `loc_trigger` is the locator of the trigger element. @@ -4959,6 +4981,7 @@ class _OverlayBase(_InputBase): """ `loc_overlay_container` is the locator of the overlay container. """ + def __init__( self, page: Page, @@ -5082,7 +5105,8 @@ def expect_placement(self, value: str, *, timeout: Timeout = None) -> None: class Popover(_OverlayBase): - """ Popover control for :func:`~shiny.ui.popover` """ + """Popover control for :func:`~shiny.ui.popover`""" + loc_trigger: Locator """ `loc_trigger` is the locator of the trigger element. @@ -5095,6 +5119,7 @@ class Popover(_OverlayBase): """ `loc_overlay_container` is the locator of the overlay container. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the Popover class. @@ -5143,7 +5168,8 @@ def toggle(self, timeout: Timeout = None) -> None: class Tooltip(_OverlayBase): - """ Tooltip control for :func:`~shiny.ui.tooltip` """ + """Tooltip control for :func:`~shiny.ui.tooltip`""" + loc_container: Locator """ `loc_container` is the locator of the container of the input. @@ -5164,6 +5190,7 @@ class Tooltip(_OverlayBase): """ `loc_overlay_container` is the locator of the overlay container. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the Tooltip class. @@ -5214,7 +5241,8 @@ def toggle(self, timeout: Timeout = None) -> None: class _NavItemBase(_InputWithContainer): - """ A Base mixin class for Nav and NavItem controls """ + """A Base mixin class for Nav and NavItem controls""" + def nav_item( self, value: str, @@ -5332,7 +5360,7 @@ def expect_nav_titles( class NavItem(_InputWithContainer): - """ NavItem control for :func:`~shiny.ui.nav_item` """ + """NavItem control for :func:`~shiny.ui.nav_item`""" """ `Locator` for the content of the nav item. @@ -5345,6 +5373,7 @@ class NavItem(_InputWithContainer): """ `Locator` for the nav item container. """ + def __init__(self, page: Page, id: str, data_value: str) -> None: """ Initializes a new instance of the NavItem class. @@ -5417,7 +5446,7 @@ def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> Non class NavsetTab(_NavItemBase): - """ NavsetTab control for :func:`~shiny.ui.navset_tab` """ + """NavsetTab control for :func:`~shiny.ui.navset_tab`""" loc: Locator """ @@ -5427,6 +5456,7 @@ class NavsetTab(_NavItemBase): """ `Locator` for the nav set tab container. """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetTab class. @@ -5447,7 +5477,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetPill(_NavItemBase): - """ NavsetPill control for :func:`~shiny.ui.navset_pill` """ + """NavsetPill control for :func:`~shiny.ui.navset_pill`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetPill class. @@ -5468,7 +5499,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetUnderline(_NavItemBase): - """ NavsetUnderline control for :func:`~shiny.ui.navset_underline` """ + """NavsetUnderline control for :func:`~shiny.ui.navset_underline`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetUnderline class. @@ -5489,7 +5521,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetPillList(_NavItemBase): - """ NavsetPillList control for :func:`~shiny.ui.navset_pill_list` """ + """NavsetPillList control for :func:`~shiny.ui.navset_pill_list`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetPillList class. @@ -5510,7 +5543,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardTab(_NavItemBase): - """ NavsetCardTab control for :func:`~shiny.ui.navset_card_tab` """ + """NavsetCardTab control for :func:`~shiny.ui.navset_card_tab`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetCardTab class. @@ -5531,7 +5565,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardPill(_NavItemBase): - """ NavsetCardPill control for :func:`~shiny.ui.navset_card_pill` """ + """NavsetCardPill control for :func:`~shiny.ui.navset_card_pill`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetCardPill class. @@ -5552,7 +5587,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardUnderline(_NavItemBase): - """ NavsetCardUnderline control for :func:`~shiny.ui.navset_card_underline` """ + """NavsetCardUnderline control for :func:`~shiny.ui.navset_card_underline`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetCardUnderline class. @@ -5573,7 +5609,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetHidden(_NavItemBase): - """ NavsetHidden control for :func:`~shiny.ui.navset_hidden` """ + """NavsetHidden control for :func:`~shiny.ui.navset_hidden`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetHidden class. @@ -5594,7 +5631,8 @@ def __init__(self, page: Page, id: str) -> None: class NavsetBar(_NavItemBase): - """ NavsetBar control for :func:`~shiny.ui.navset_bar` """ + """NavsetBar control for :func:`~shiny.ui.navset_bar`""" + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the NavsetBar class. @@ -6073,6 +6111,7 @@ class DownloadLink(_InputActionBase): """ DownloadLink control for :func:`~shiny.ui.download_link` """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the DownloadLink class. @@ -6098,6 +6137,7 @@ class DownloadButton( """ DownloadButton control for :func:`~shiny.ui.download_button` """ + def __init__(self, page: Page, id: str) -> None: """ Initializes a new instance of the DownloadButton class. From 55a8ab7be512baca480eb167de518160180ab86a Mon Sep 17 00:00:00 2001 From: Karan Gathani Date: Thu, 6 Jun 2024 11:53:30 -0700 Subject: [PATCH 03/11] Check for playwright, pytest and pytest-playwright when users import shiny.playwright --- shiny/playwright/__init__.py | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/shiny/playwright/__init__.py b/shiny/playwright/__init__.py index 815c64b17..50b543353 100644 --- a/shiny/playwright/__init__.py +++ b/shiny/playwright/__init__.py @@ -5,12 +5,21 @@ "The shiny.playwright module requires the playwright package to be installed." " Please install it with this command:" "\n\n pip install playwright" - "\n\n", - "If you are using pytest to test your code," - " you can install the pytest-playwright shim package with this command:", - "\n\n pip install pytest-playwright", ) +try: + import pytest # noqa: F401 # pyright: ignore[reportUnusedImport, reportMissingTypeStubs] + + try: + import pytest_playwright # noqa: F401 # pyright: ignore[reportUnusedImport, reportMissingTypeStubs] + except ImportError: + raise ImportError( + "If you are using pytest to test your app," + " you can install the pytest-playwright shim package with this command:", + "\n\n pip install pytest-playwright", + ) +except ImportError: + pass from . import controls, expect __all__ = ["expect", "controls"] From f15c670b6abfbc2e45431e5ac0afde102cc4e306 Mon Sep 17 00:00:00 2001 From: Karan Gathani Date: Thu, 6 Jun 2024 11:54:21 -0700 Subject: [PATCH 04/11] Add PR number in changelog entry --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b062b3e77..c012a65f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,7 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### New features -* Expose shiny.pytest, shiny.run and shiny.playwright modules that allow users to testing their Shiny apps. (#1448) +* Expose shiny.pytest, shiny.run and shiny.playwright modules that allow users to testing their Shiny apps. (#1448, #1456) * Added busy indicators to provide users with a visual cue when the server is busy calculating outputs or otherwise serving requests to the client. More specifically, a spinner is shown on each calculating/recalculating output, and a pulsing banner is shown at the top of the page when the app is otherwise busy. Use the new `ui.busy_indicator.options()` function to customize the appearance of the busy indicators and `ui.busy_indicator.use()` to disable/enable them. (#918) From 180b589b798b764ab5c7bbaf1efe634f23d978f0 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Fri, 7 Jun 2024 16:42:30 -0400 Subject: [PATCH 05/11] Apply suggestions from code review --- shiny/playwright/controls/_controls.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index 7ab20276a..99c60bd3d 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -149,11 +149,11 @@ class _InputBaseP(Protocol): class _InputWithContainerP(_InputBaseP, Protocol): - """A mixin class representing inputs with a container.""" + """A protocol class representing inputs with a container.""" loc_container: Locator """ - `loc_container` is the locator of the container of the input. + `Locator` for the container of the input. """ From fb34e3bba3411ca6d27064de1beb3af9bf04ae58 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Fri, 7 Jun 2024 16:47:28 -0400 Subject: [PATCH 06/11] Defaults to `None` --- shiny/playwright/controls/_controls.py | 340 +++++++++++-------------- 1 file changed, 148 insertions(+), 192 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index 99c60bd3d..ec452ae5e 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -122,10 +122,10 @@ def set_text( The text to set. delay The delay between key presses in milliseconds. - Defaults to None. + Defaults to `None`. timeout The maximum time to wait for the text to be set. - Defaults to None. + Defaults to `None`. """ # TODO-future; Composable set() method loc.fill("", timeout=timeout) # Reset the value @@ -287,8 +287,7 @@ def __init__( loc_container The locator of the container of the input. loc_label - The locator of the label of the input. - Defaults to None. + The locator of the label of the input. Defaults to `None`. """ super().__init__( page, @@ -317,8 +316,7 @@ def expect_label( value The expected value of the label. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ playwright_expect(self.loc_label).to_have_text(value, timeout=timeout) @@ -343,8 +341,7 @@ def expect_width( value The expected value of the width attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "width", value=value, timeout=timeout) @@ -369,8 +366,7 @@ def expect_width( value The expected value of the width attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc_container, "width", value=value, timeout=timeout @@ -387,8 +383,7 @@ def set(self: _InputBaseP, value: str, *, timeout: Timeout = None) -> None: value The text to set. timeout - The maximum time to wait for the text to be set. - Defaults to None. + The maximum time to wait for the text to be set. Defaults to `None`. """ set_text(self.loc, value, timeout=timeout) @@ -410,8 +405,7 @@ def expect_value( value The expected value of the input. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ playwright_expect(self.loc).to_have_value(value, timeout=timeout) @@ -455,8 +449,7 @@ def expect_min( value The expected value of the min attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "min", value=value, timeout=timeout) @@ -474,8 +467,7 @@ def expect_max( value The expected value of the max attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "max", value=value, timeout=timeout) @@ -493,8 +485,7 @@ def expect_step( value The expected value of the step attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "step", value=value, timeout=timeout) @@ -514,8 +505,7 @@ def expect_spellcheck( value The expected value of the spellcheck attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ # self.spellcheck.expect_to_have_value(value, timeout=timeout) expect_attribute_to_have_value( @@ -538,8 +528,7 @@ def expect_placeholder( value The expected value of the placeholder attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "placeholder", value=value, timeout=timeout @@ -561,8 +550,7 @@ def expect_autocomplete( value The expected value of the autocomplete attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "autocomplete", value=value, timeout=timeout @@ -658,8 +646,7 @@ def expect_width( value The expected value of the width attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_to_have_style(self.loc_container, "width", value, timeout=timeout) @@ -708,8 +695,7 @@ def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: value The expected value of the width attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ if value is None: expect_to_have_style(self.loc_container, "width", None, timeout=timeout) @@ -727,8 +713,7 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: value The expected value of the height attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_to_have_style(self.loc, "height", value, timeout=timeout) @@ -741,8 +726,7 @@ def expect_cols(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value of the cols attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "cols", value=value, timeout=timeout) @@ -755,8 +739,7 @@ def expect_rows(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value of the rows attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "rows", value=value, timeout=timeout) @@ -774,8 +757,7 @@ def expect_resize( value The expected value of the resize attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "resize", value=value, timeout=timeout) @@ -793,8 +775,7 @@ def expect_autoresize( value The expected value of the autoresize attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ _expect_class_value( self.loc, @@ -838,8 +819,7 @@ def __init__( id The id of the input select. select_class - The class of the select element. - Defaults to "". + The class of the select element. Defaults to "". """ super().__init__( page, @@ -864,8 +844,7 @@ def set( selected The value(s) of the selected option(s). timeout - The maximum time to wait for the selection to be set. - Defaults to None. + The maximum time to wait for the selection to be set. Defaults to `None`. """ if isinstance(selected, str): selected = [selected] @@ -886,8 +865,7 @@ def expect_choices( choices The expected choices of the input select. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ """Expect choices to be in order""" # Playwright doesn't like lists of size 0. Instead, check for empty locator @@ -918,8 +896,7 @@ def expect_selected( selected The expected value(s) of the selected option(s). timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ """Expect choices to be in order""" # Playwright doesn't like lists of size 0 @@ -957,8 +934,7 @@ def expect_choice_groups( choice_groups The expected choice groups of the input select. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ """Expect choices to be in order""" # Playwright doesn't like lists of size 0. Instead, use `None` @@ -990,8 +966,7 @@ def expect_choice_labels( choice_labels The expected choice labels of the input select. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ # Playwright doesn't like lists of size 0. Instead, use `None` if len(choice_labels) == 0: @@ -1009,8 +984,7 @@ def expect_multiple(self, multiple: bool, *, timeout: Timeout = None) -> None: multiple Whether the input select allows multiple selections. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ _expect_multiple(self.loc, multiple, timeout=timeout) @@ -1023,8 +997,7 @@ def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value of the size attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, @@ -1064,8 +1037,7 @@ def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: selectize Whether the input select is selectize. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ # class_=None if selectize else "form-select", _expect_class_value( @@ -1105,8 +1077,7 @@ def click(self, *, timeout: Timeout = None, **kwargs: object) -> None: Parameters ---------- timeout - The maximum time to wait for the input action to be clicked. - Defaults to None. + The maximum time to wait for the input action to be clicked. Defaults to `None`. """ self.loc.click(timeout=timeout, **kwargs) # pyright: ignore[reportArgumentType] @@ -1172,8 +1143,7 @@ def click(self, *, timeout: Timeout = None): Parameters ---------- timeout - The maximum time to wait for the input dark mode to be clicked. - Defaults to None. + The maximum time to wait for the input dark mode to be clicked. Defaults to `None`. """ self.loc.click(timeout=timeout) return self @@ -1187,8 +1157,7 @@ def expect_mode(self, value: str, *, timeout: Timeout = None): value The expected value of the mode attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "mode", value=value, timeout=timeout) self.expect_page_mode(value, timeout=timeout) @@ -1203,8 +1172,7 @@ def expect_page_mode(self, value: str, *, timeout: Timeout = None): value The expected value of the page mode. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.page.locator("html"), "data-bs-theme", value=value, timeout=timeout @@ -1220,8 +1188,7 @@ def expect_wc_attribute(self, value: str, *, timeout: Timeout = None): value The expected value of the wc attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "attribute", value=value, timeout=timeout @@ -1273,8 +1240,7 @@ def expect_state( value The expected value of the state. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc.locator("> bslib-switch-inline"), @@ -1292,8 +1258,7 @@ def expect_label(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected value of the label. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ self.expect_label_ready(value, timeout=timeout) @@ -1306,8 +1271,7 @@ def expect_label_ready(self, value: PatternOrStr, *, timeout: Timeout = None): value The expected value of the label. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ self.expect_label_state("ready", value, timeout=timeout) @@ -1320,8 +1284,7 @@ def expect_label_busy(self, value: PatternOrStr, *, timeout: Timeout = None): value The expected value of the label. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ self.expect_label_state("busy", value, timeout=timeout) @@ -1338,8 +1301,7 @@ def expect_label_state( value The expected value of the label. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ playwright_expect( self.loc.locator(f"> bslib-switch-inline > span[slot='{state}']") @@ -1354,8 +1316,7 @@ def expect_auto_reset(self, value: bool, timeout: Timeout = None): value The expected value of the auto-reset attribute. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, @@ -1437,8 +1398,7 @@ def set(self, value: bool, *, timeout: Timeout = None, **kwargs: object) -> None value The value of the input checkbox. timeout - The maximum time to wait for the input checkbox to be set. - Defaults to None. + The maximum time to wait for the input checkbox to be set. Defaults to `None`. """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) @@ -1453,8 +1413,7 @@ def toggle(self, *, timeout: Timeout = None, **kwargs: object) -> None: Parameters ---------- timeout - The maximum time to wait for the input checkbox to be toggled. - Defaults to None. + The maximum time to wait for the input checkbox to be toggled. Defaults to `None`. """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) @@ -1469,8 +1428,7 @@ def expect_checked(self, value: bool, *, timeout: Timeout = None) -> None: value Whether the input checkbox is checked. timeout - The maximum time to wait for the expectation to be fulfilled. - Defaults to None. + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ if value: self.expect.to_be_checked(timeout=timeout) @@ -2554,7 +2512,7 @@ def expect_time_format(self, value: AttrValue, *, timeout: Timeout = None) -> No value : AttrValue The expected value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-time-format", value=value, timeout=timeout @@ -2569,7 +2527,7 @@ def expect_timezone(self, value: AttrValue, *, timeout: Timeout = None) -> None: value : AttrValue The expected value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-timezone", value=value, timeout=timeout @@ -2584,7 +2542,7 @@ def expect_drag_range(self, value: AttrValue, *, timeout: Timeout = None) -> Non value : AttrValue The expected value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-drag-interval", value=value, timeout=timeout @@ -2748,7 +2706,7 @@ def expect_value(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value : PatternOrStr The expected value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ playwright_expect(self.loc_irs_label).to_have_text(value, timeout=timeout) @@ -2767,10 +2725,9 @@ def set( value : str The value to set the slider to. max_err_values : int, optional - The maximum number of error values to display if the value is not found. - Defaults to 15. + The maximum number of error values to display if the value is not found. Defaults to 15. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ self._wait_for_container(timeout=timeout) @@ -2838,7 +2795,7 @@ def expect_value( value : Tuple[PatternOrStr, PatternOrStr] The expected value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ if all_missing(*value): raise ValueError("Both `value` tuple entries cannot be `MISSING_TYPE`") @@ -2896,10 +2853,9 @@ def set( value : Tuple[str, str] | Tuple[str, MISSING_TYPE] | Tuple[MISSING_TYPE, str] The value to set the slider to. max_err_values : int, optional - The maximum number of error values to display if the value is not found. - Defaults to 15. + The maximum number of error values to display if the value is not found. Defaults to 15. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ if all_missing(*value): raise ValueError("Both `value` tuple entries cannot be `MISSING_TYPE`") @@ -2977,7 +2933,7 @@ def expect_value( value : PatternOrStr The expected value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ # if value is None: # self.expect.to_be_empty(timeout=timeout) @@ -2998,7 +2954,7 @@ def expect_min_date( value : str The expected `data-min-date` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-min-date", value=value, timeout=timeout @@ -3018,7 +2974,7 @@ def expect_max_date( value : str The expected `data-max-date` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-max-date", value=value, timeout=timeout @@ -3038,7 +2994,7 @@ def expect_format( value : str The expected `data-date-format` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-date-format", value=value, timeout=timeout @@ -3058,7 +3014,7 @@ def expect_startview( value : str The expected `data-date-start-view` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-date-start-view", value=value, timeout=timeout @@ -3078,7 +3034,7 @@ def expect_weekstart( value : int The expected `data-date-week-start` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ if isinstance(value, int): value = str(value) @@ -3100,7 +3056,7 @@ def expect_language( value : str The expected `data-date-language` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-date-language", value=value, timeout=timeout @@ -3121,7 +3077,7 @@ def expect_autoclose( value : Literal["true", "false"] The expected `data-date-autoclose` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-date-autoclose", value=value, timeout=timeout @@ -3141,7 +3097,7 @@ def expect_datesdisabled( value : Optional[list[str]] The expected `data-date-dates-disabled` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ if isinstance(value, list): assert len(value) > 0, "`value` must be `None` or a non-empty list" @@ -3167,7 +3123,7 @@ def expect_daysofweekdisabled( value : Optional[list[int]] The expected `data-date-days-of-week-disabled` attribute value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ if isinstance(value, list): assert len(value) > 0, "`value` must be `None` or a non-empty list" @@ -3276,7 +3232,7 @@ def set( value : Tuple[str, str] The value to set. The first element is the start date and the second element is the end date. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to be set. Defaults to None. + The maximum time to wait for the value to be set. Defaults to `None`. """ start = value[0] end = value[1] @@ -3304,7 +3260,7 @@ def expect_value( value : Tuple[PatternOrStr, PatternOrStr] The expected value. The first element is the start date and the second element is the end date. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ if all_missing(*value): raise ValueError("Both `start_val` and `end_val` can not be `MISSING_TYPE`") @@ -3334,7 +3290,7 @@ def expect_min_date( value : AttrValue The expected minimum date. timeout : Optional[Union[int, float]] - The maximum time to wait for the minimum date to appear. Defaults to None. + The maximum time to wait for the minimum date to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_min_date(value, timeout=timeout) @@ -3355,7 +3311,7 @@ def expect_max_date( value : AttrValue The expected maximum date. timeout : Optional[Union[int, float]] - The maximum time to wait for the maximum date to appear. Defaults to None. + The maximum time to wait for the maximum date to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_max_date(value, timeout=timeout) @@ -3376,7 +3332,7 @@ def expect_format( value : AttrValue The expected format. timeout : Optional[Union[int, float]] - The maximum time to wait for the format to appear. Defaults to None. + The maximum time to wait for the format to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_format(value, timeout=timeout) @@ -3397,7 +3353,7 @@ def expect_startview( value : AttrValue The expected start view. timeout : Optional[Union[int, float]] - The maximum time to wait for the start view to appear. Defaults to None. + The maximum time to wait for the start view to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_startview(value, timeout=timeout) @@ -3418,7 +3374,7 @@ def expect_weekstart( value : int The expected week start. timeout : Optional[Union[int, float]] - The maximum time to wait for the week start to appear. Defaults to None. + The maximum time to wait for the week start to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_weekstart(value, timeout=timeout) @@ -3439,7 +3395,7 @@ def expect_language( value : AttrValue The expected language. timeout : Optional[Union[int, float]] - The maximum time to wait for the language to appear. Defaults to None. + The maximum time to wait for the language to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_language(value, timeout=timeout) @@ -3460,7 +3416,7 @@ def expect_separator( value : PatternOrStr The expected separator. timeout : Optional[Union[int, float]] - The maximum time to wait for the separator to appear. Defaults to None. + The maximum time to wait for the separator to appear. Defaults to `None`. """ playwright_expect(self.loc_separator).to_have_text(value, timeout=timeout) @@ -3481,7 +3437,7 @@ def expect_autoclose( value : Literal["true", "false"] The expected autoclose value. timeout : Optional[Union[int, float]] - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ # TODO-future; Composable expectations self.date_start.expect_autoclose(value, timeout=timeout) @@ -3542,7 +3498,7 @@ def expect_value( value The expected value. timeout - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ """Note this function will trim value and output text value before comparing them""" self.expect.to_have_text(value, timeout=timeout) @@ -3572,7 +3528,7 @@ def expect_container_tag( tag_name The expected container tag. timeout - The maximum time to wait for the container tag to appear. Defaults to None. + The maximum time to wait for the container tag to appear. Defaults to `None`. """ loc = self.loc.locator(f"xpath=self::{tag_name}") playwright_expect(loc).to_have_count(1, timeout=timeout) @@ -3590,7 +3546,7 @@ def expect_inline( inline Whether the output is inline. timeout - The maximum time to wait for the output to appear. Defaults to None. + The maximum time to wait for the output to appear. Defaults to `None`. """ tag_name = "span" if inline else "div" self.expect_container_tag(tag_name, timeout=timeout) @@ -3628,7 +3584,7 @@ def get_value(self, *, timeout: Timeout = None) -> str: Parameters ---------- timeout - The maximum time to wait for the value to appear. Defaults to None. + The maximum time to wait for the value to appear. Defaults to `None`. """ return self.loc.inner_text(timeout=timeout) @@ -3665,7 +3621,7 @@ def expect_has_placeholder( placeholder Whether the code output has a placeholder. timeout - The maximum time to wait for the placeholder to appear. Defaults to None. + The maximum time to wait for the placeholder to appear. Defaults to `None`. """ _expect_class_value( self.loc, @@ -3748,7 +3704,7 @@ def expect_height( value The expected height. timeout - The maximum time to wait for the height to appear. Defaults to None. + The maximum time to wait for the height to appear. Defaults to `None`. """ expect_to_have_style(self.loc, "height", value, timeout=timeout) @@ -3766,7 +3722,7 @@ def expect_width( value The expected width. timeout - The maximum time to wait for the width to appear. Defaults to None. + The maximum time to wait for the width to appear. Defaults to `None`. """ expect_to_have_style(self.loc, "width", value, timeout=timeout) @@ -3784,7 +3740,7 @@ def expect_img_src( value The expected src. timeout - The maximum time to wait for the src to appear. Defaults to None. + The maximum time to wait for the src to appear. Defaults to `None`. """ expect_attribute_to_have_value(self.loc_img, "src", value, timeout=timeout) @@ -3802,7 +3758,7 @@ def expect_img_width( value The expected width. timeout - The maximum time to wait for the width to appear. Defaults to None. + The maximum time to wait for the width to appear. Defaults to `None`. """ expect_attribute_to_have_value(self.loc_img, "width", value, timeout=timeout) @@ -3820,7 +3776,7 @@ def expect_img_height( value The expected height. timeout - The maximum time to wait for the height to appear. Defaults to None. + The maximum time to wait for the height to appear. Defaults to `None`. """ expect_attribute_to_have_value(self.loc_img, "height", value, timeout=timeout) @@ -3838,7 +3794,7 @@ def expect_img_alt( value The expected alt text. timeout - The maximum time to wait for the alt text to appear. Defaults to None. + The maximum time to wait for the alt text to appear. Defaults to `None`. """ expect_attribute_to_have_value(self.loc_img, "alt", value, timeout=timeout) @@ -3962,7 +3918,7 @@ def expect_cell( col The column number. timeout - The maximum time to wait for the text to appear. Defaults to None. + The maximum time to wait for the text to appear. Defaults to `None`. """ assert_type(row, int) assert_type(col, int) @@ -3986,7 +3942,7 @@ def expect_column_labels( labels The expected column labels. If None, it asserts that the table has no column labels. timeout - The maximum time to wait for the column labels to appear. Defaults to None. + The maximum time to wait for the column labels to appear. Defaults to `None`. """ if isinstance(labels, list) and len(labels) == 0: labels = None @@ -4018,7 +3974,7 @@ def expect_column_text( text The expected text in the column. timeout - The maximum time to wait for the text to appear. Defaults to None. + The maximum time to wait for the text to appear. Defaults to `None`. """ assert_type(col, int) playwright_expect( @@ -4042,7 +3998,7 @@ def expect_n_col( n The expected number of columns in the table. timeout - The maximum time to wait for the table to have the expected number of columns. Defaults to None. + The maximum time to wait for the table to have the expected number of columns. Defaults to `None`. """ playwright_expect( # self.loc.locator("xpath=./table/thead/tr[1]/(td|th)") @@ -4066,7 +4022,7 @@ def expect_n_row( n The expected number of rows in the table. timeout - The maximum time to wait for the table to have the expected number of rows. Defaults to None. + The maximum time to wait for the table to have the expected number of rows. Defaults to `None`. """ playwright_expect(self.loc.locator("xpath=./table/tbody/tr")).to_have_count( n, @@ -4126,7 +4082,7 @@ def expect_text(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected text in the sidebar. timeout - The maximum time to wait for the text to appear. Defaults to None. + The maximum time to wait for the text to appear. Defaults to `None`. """ playwright_expect(self.loc).to_have_text(value, timeout=timeout) @@ -4141,7 +4097,7 @@ def expect_position( position The expected position of the sidebar. timeout - The maximum time to wait for the sidebar to appear. Defaults to None. + The maximum time to wait for the sidebar to appear. Defaults to `None`. """ is_right_sidebar = position == "right" _expect_class_value( @@ -4160,7 +4116,7 @@ def expect_handle(self, exists: bool, *, timeout: Timeout = None) -> None: exists True if the sidebar handle should exist, False otherwise. timeout - The maximum time to wait for the sidebar handle to appear. Defaults to None. + The maximum time to wait for the sidebar handle to appear. Defaults to `None`. """ playwright_expect(self.loc_handle).to_have_count(int(exists), timeout=timeout) @@ -4173,7 +4129,7 @@ def expect_open(self, open: bool, *, timeout: Timeout = None) -> None: open True if the sidebar should be open, False otherwise. timeout - The maximum time to wait for the sidebar to open or close. Defaults to None. + The maximum time to wait for the sidebar to open or close. Defaults to `None`. """ playwright_expect(self.loc_handle).to_have_attribute( "aria-expanded", str(open).lower(), timeout=timeout @@ -4188,7 +4144,7 @@ def set(self, open: bool, *, timeout: Timeout = None) -> None: open True if the sidebar should be open, False otherwise. timeout - The maximum time to wait for the sidebar to open or close. Defaults to None. + The maximum time to wait for the sidebar to open or close. Defaults to `None`. """ if open ^ (self.loc_handle.get_attribute("aria-expanded") == "true"): self.toggle(timeout=timeout) @@ -4200,7 +4156,7 @@ def toggle(self, *, timeout: Timeout = None) -> None: Parameters ---------- timeout - The maximum time to wait for the sidebar to toggle. Defaults to None. + The maximum time to wait for the sidebar to toggle. Defaults to `None`. """ self.loc_handle.wait_for(state="visible", timeout=timeout) self.loc_handle.scroll_into_view_if_needed(timeout=timeout) @@ -4234,7 +4190,7 @@ def expect_body( text The expected text or a list of expected texts. timeout - The maximum time to wait for the text to appear. Defaults to None. + The maximum time to wait for the text to appear. Defaults to `None`. """ playwright_expect(self.loc).to_have_text( text, @@ -4272,7 +4228,7 @@ def expect_footer( text The expected text in the footer section. timeout - The maximum time to wait for the footer text to appear. Defaults to None. + The maximum time to wait for the footer text to appear. Defaults to `None`. """ playwright_expect(self.loc_footer).to_have_text( text, @@ -4313,7 +4269,7 @@ def open_full_screen( Parameters ---------- timeout - The maximum time to wait for the card to open in full screen mode. Defaults to None. + The maximum time to wait for the card to open in full screen mode. Defaults to `None`. """ self.loc_title.hover(timeout=timeout) self._loc_fullscreen.wait_for(state="visible", timeout=timeout) @@ -4328,7 +4284,7 @@ def close_full_screen( Parameters ---------- timeout - The maximum time to wait for the card to close from full screen mode. Defaults to None. + The maximum time to wait for the card to close from full screen mode. Defaults to `None`. """ self._loc_close_button.click(timeout=timeout) @@ -4343,7 +4299,7 @@ def expect_full_screen_open( open True if the card is expected to be in full screen mode, False otherwise. timeout - The maximum time to wait for the verification. Defaults to None. + The maximum time to wait for the verification. Defaults to `None`. """ playwright_expect(self._loc_close_button).to_have_count( int(open), timeout=timeout @@ -4360,7 +4316,7 @@ def expect_full_screen_available( available True if the value box is expected to be available for full screen mode, False otherwise. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self._loc_fullscreen).to_have_count( int(available), timeout=timeout @@ -4439,7 +4395,7 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: value The expected height value. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ expect_to_have_style(self.loc_container, "max-height", value, timeout=timeout) @@ -4457,7 +4413,7 @@ def expect_title( text The expected text pattern or string. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_title).to_have_text( @@ -4479,7 +4435,7 @@ def expect_value( text The expected text pattern or string. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc).to_have_text( text, @@ -4501,7 +4457,7 @@ def expect_body( The expected text pattern or list of patterns/strings. Note: If testing against multiple elements, text should be an array timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_body).to_have_text( text, @@ -4577,7 +4533,7 @@ def expect_header( The expected text pattern or string Note: None if the header is expected to not exist. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ if text is None: playwright_expect(self.loc_title).to_have_count(0, timeout=timeout) @@ -4612,7 +4568,7 @@ def expect_footer( The expected text pattern or string Note: None if the footer is expected to not exist. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ if text is None: playwright_expect(self.loc_footer).to_have_count(0, timeout=timeout) @@ -4628,7 +4584,7 @@ def expect_max_height(self, value: StyleValue, *, timeout: Timeout = None) -> No value The expected maximum height value. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ expect_to_have_style(self.loc_container, "max-height", value, timeout=timeout) @@ -4641,7 +4597,7 @@ def expect_min_height(self, value: StyleValue, *, timeout: Timeout = None) -> No value The expected minimum height value. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ expect_to_have_style(self.loc_container, "min-height", value, timeout=timeout) @@ -4654,7 +4610,7 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: value The expected height value. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ expect_to_have_style(self.loc_container, "height", value, timeout=timeout) @@ -4713,7 +4669,7 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: value The expected height. timeout - The maximum time to wait for the height to be visible and interactable. Defaults to None. + The maximum time to wait for the height to be visible and interactable. Defaults to `None`. """ expect_to_have_style(self.loc_container, "height", value, timeout=timeout) @@ -4726,7 +4682,7 @@ def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: value The expected width. timeout - The maximum time to wait for the width to be visible and interactable. Defaults to None. + The maximum time to wait for the width to be visible and interactable. Defaults to `None`. """ expect_to_have_style(self.loc_container, "width", value, timeout=timeout) @@ -4764,7 +4720,7 @@ def expect_panels( value The expected panels. timeout - The maximum time to wait for the panels to be visible and interactable. Defaults to None. + The maximum time to wait for the panels to be visible and interactable. Defaults to `None`. """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, @@ -4790,7 +4746,7 @@ def set( selected The selected accordion panel(s). timeout - The maximum time to wait for the accordion panel to be visible and interactable. Defaults to None. + The maximum time to wait for the accordion panel to be visible and interactable. Defaults to `None`. """ if isinstance(selected, str): selected = [selected] @@ -4891,7 +4847,7 @@ def expect_label(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected text pattern or string. timeout - The maximum time to wait for the label to appear. Defaults to None. + The maximum time to wait for the label to appear. Defaults to `None`. """ playwright_expect(self.loc_label).to_have_text(value, timeout=timeout) @@ -4904,7 +4860,7 @@ def expect_body(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected text pattern or string. timeout - The maximum time to wait for the body to appear. Defaults to None. + The maximum time to wait for the body to appear. Defaults to `None`. """ playwright_expect(self.loc_body).to_have_text(value, timeout=timeout) @@ -4917,7 +4873,7 @@ def expect_icon(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected text pattern or string. timeout - The maximum time to wait for the icon to appear. Defaults to None. + The maximum time to wait for the icon to appear. Defaults to `None`. """ playwright_expect(self.loc_icon).to_have_text(value, timeout=timeout) @@ -4930,7 +4886,7 @@ def expect_open(self, is_open: bool, *, timeout: Timeout = None) -> None: is_open True if the accordion panel is expected to be open, False otherwise. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ _expect_class_value(self.loc_body, "show", is_open, timeout=timeout) @@ -4944,7 +4900,7 @@ def set(self, open: bool, *, timeout: Timeout = None) -> None: open True if the control is expected to be open, False otherwise. timeout - The maximum time to wait for the control to be visible and interactable. Defaults to None. + The maximum time to wait for the control to be visible and interactable. Defaults to `None`. """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) @@ -4959,7 +4915,7 @@ def toggle(self, *, timeout: Timeout = None) -> None: Parameters ---------- timeout - The maximum time to wait for the control to be visible and interactable. Defaults to None. + The maximum time to wait for the control to be visible and interactable. Defaults to `None`. """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) @@ -5047,7 +5003,7 @@ def get_loc_overlay_container(self, *, timeout: Timeout = None) -> Locator: Parameters ---------- timeout - The maximum time to wait for the overlay container to appear. Defaults to None. + The maximum time to wait for the overlay container to appear. Defaults to `None`. """ return self.page.locator(f"#{self._get_overlay_id(timeout=timeout)}") @@ -5060,7 +5016,7 @@ def expect_body(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected text pattern or string. timeout - The maximum time to wait for the overlay body to appear. Defaults to None. + The maximum time to wait for the overlay body to appear. Defaults to `None`. """ playwright_expect(self.get_loc_overlay_body(timeout=timeout)).to_have_text( value, timeout=timeout @@ -5075,7 +5031,7 @@ def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: active True if the overlay is expected to be active, False otherwise. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ value = re.compile(r".*") if active else None return expect_attribute_to_have_value( @@ -5094,7 +5050,7 @@ def expect_placement(self, value: str, *, timeout: Timeout = None) -> None: value The expected placement value. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ return expect_attribute_to_have_value( loc=self.get_loc_overlay_container(timeout=timeout), @@ -5148,7 +5104,7 @@ def set(self, open: bool, timeout: Timeout = None) -> None: open True if the popover is expected to be open, False otherwise. timeout - The maximum time to wait for the popover to be visible and interactable. Defaults to None. + The maximum time to wait for the popover to be visible and interactable. Defaults to `None`. """ if open ^ self.get_loc_overlay_body(timeout=timeout).count() > 0: self.toggle() @@ -5160,7 +5116,7 @@ def toggle(self, timeout: Timeout = None) -> None: Parameters ---------- timeout - The maximum time to wait for the popover to be visible and interactable. Defaults to None. + The maximum time to wait for the popover to be visible and interactable. Defaults to `None`. """ self.loc_trigger.wait_for(state="visible", timeout=timeout) self.loc_trigger.scroll_into_view_if_needed(timeout=timeout) @@ -5219,7 +5175,7 @@ def set(self, open: bool, timeout: Timeout = None) -> None: open True if the tooltip is expected to be open, False otherwise. timeout - The maximum time to wait for the tooltip to be visible and interactable. Defaults to None. + The maximum time to wait for the tooltip to be visible and interactable. Defaults to `None`. """ if open ^ self.get_loc_overlay_body(timeout=timeout).count() > 0: self.toggle(timeout=timeout) @@ -5233,7 +5189,7 @@ def toggle(self, timeout: Timeout = None) -> None: Parameters ---------- timeout - The maximum time to wait for the tooltip to be visible and interactable. Defaults to None. + The maximum time to wait for the tooltip to be visible and interactable. Defaults to `None`. """ self.loc_trigger.wait_for(state="visible", timeout=timeout) self.loc_trigger.scroll_into_view_if_needed(timeout=timeout) @@ -5269,7 +5225,7 @@ def expect_value(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value The expected value. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ # data attribute of active tab and compare with value playwright_expect( @@ -5292,7 +5248,7 @@ def get_loc_active_content(self, *, timeout: Timeout = None) -> Locator: Parameters ---------- timeout - The maximum time to wait for the locator to appear. Defaults to None. + The maximum time to wait for the locator to appear. Defaults to `None`. """ datatab_id = self.loc_container.get_attribute("data-tabsetid", timeout=timeout) return self.page.locator( @@ -5308,7 +5264,7 @@ def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> Non value The expected content. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.get_loc_active_content()).to_have_text( value, timeout=timeout @@ -5328,7 +5284,7 @@ def expect_nav_values( value The expected nav values. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, @@ -5354,7 +5310,7 @@ def expect_nav_titles( value The expected nav titles. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ self.expect.to_have_text(value, timeout=timeout) @@ -5414,7 +5370,7 @@ def click(self, *, timeout: Timeout = None) -> None: Parameters ---------- timeout - The maximum time to wait for the nav item to be visible and interactable. Defaults to None. + The maximum time to wait for the nav item to be visible and interactable. Defaults to `None`. """ self.loc.click(timeout=timeout) @@ -5427,7 +5383,7 @@ def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: active True if the nav item is expected to be active, False otherwise. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ _expect_class_value(self.loc, "active", active, timeout=timeout) @@ -5440,7 +5396,7 @@ def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> Non value The expected text pattern or string. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_content).to_have_text(value, timeout=timeout) @@ -5717,7 +5673,7 @@ def expect_n_row(self, row_number: int, *, timeout: Timeout = None): row_number The expected number of rows. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_body.locator("> tr")).to_have_count( row_number, timeout=timeout @@ -5743,7 +5699,7 @@ def expect_cell( col The column number of the cell. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ assert_type(row, int) assert_type(col, int) @@ -5769,7 +5725,7 @@ def expect_column_labels( edit True if the data frame is in edit mode, False otherwise. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ if isinstance(labels, list) and len(labels) == 0: labels = None @@ -5839,7 +5795,7 @@ def expect_column_label( text The expected text in the column. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ assert_type(col, int) # It's zero based, nth(0) selects the first element. @@ -5862,7 +5818,7 @@ def expect_n_col( n The expected number of columns. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_column_label).to_have_count( n, @@ -5889,7 +5845,7 @@ def expect_cell_class( class_ The expected class of the cell. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ expect_to_have_class( self.cell_locator(row=row, col=col), @@ -5911,7 +5867,7 @@ def select_rows( rows The list of row numbers to select. timeout - The maximum time to wait for the action to complete. Defaults to None. + The maximum time to wait for the action to complete. Defaults to `None`. """ if len(rows) > 1: rows = sorted(rows) @@ -5985,7 +5941,7 @@ def edit_cell( col The column number of the cell. timeout - The maximum time to wait for the action to complete. Defaults to None. + The maximum time to wait for the action to complete. Defaults to `None`. """ cell = self.cell_locator(row=row, col=col) @@ -6010,7 +5966,7 @@ def set_column_sort( col The column number to sort. timeout - The maximum time to wait for the action to complete. Defaults to None. + The maximum time to wait for the action to complete. Defaults to `None`. """ self.loc_column_label.nth(col).click(timeout=timeout) @@ -6034,7 +5990,7 @@ def set_column_filter( text The text to filter the column. timeout - The maximum time to wait for the action to complete. Defaults to None. + The maximum time to wait for the action to complete. Defaults to `None`. """ if isinstance(text, str): self.loc_column_filter.nth(col).locator("> input").fill( @@ -6074,7 +6030,7 @@ def save_cell( col The column number of the cell. timeout - The maximum time to wait for the action to complete. Defaults to None. + The maximum time to wait for the action to complete. Defaults to `None`. """ self.edit_cell(text, row=row, col=col, timeout=timeout) self.cell_locator(row=row, col=col).locator("> textarea").press(save_key) @@ -6099,7 +6055,7 @@ def expect_cell_title( message The expected validation message of the cell. timeout - The maximum time to wait for the expectation to pass. Defaults to None. + The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.cell_locator(row=row, col=col)).to_have_attribute( name="title", value=message, timeout=timeout From df5b8f59996824bd79c05faf38e3f7193d3a2758 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Fri, 7 Jun 2024 17:26:57 -0400 Subject: [PATCH 07/11] Update _controls.py --- shiny/playwright/controls/_controls.py | 660 ++++++++++++------------- 1 file changed, 319 insertions(+), 341 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index ec452ae5e..e148873ab 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -112,20 +112,18 @@ def set_text( timeout: Timeout = None, ) -> None: """ - Sets the text of an element. + Sets the text of a DOM element. Parameters ---------- loc - The locator of the element. + The Playwright `Locator` of the element. text The text to set. delay - The delay between key presses in milliseconds. - Defaults to `None`. + The delay between key presses in milliseconds. Defaults to `None`. timeout - The maximum time to wait for the text to be set. - Defaults to `None`. + The maximum time to wait for the text to be set. Defaults to `None`. """ # TODO-future; Composable set() method loc.fill("", timeout=timeout) # Reset the value @@ -158,12 +156,21 @@ class _InputWithContainerP(_InputBaseP, Protocol): class _InputBase: - """A base class representing inputs.""" + """A base class representing shiny UI inputs.""" # timeout: Timeout id: str + """ + The browser DOM `id` of the input. + """ loc: Locator + """ + The Playwright `Locator` of the input. + """ page: Page + """ + The Playwright `Page` of the Shiny app. + """ def __init__( self, @@ -182,6 +189,8 @@ def __init__( @property # TODO; Can not publicly find `LocatorAssertions` in `playwright` def expect(self): + """Expectation method equivalent to `playwright.expect(self.loc)`""" + # TODO-karan-test: Search for `.loc)` and convert `expect(FOO.loc)` to `FOO.expect`. If we don't like the helper API, we should remove it. return playwright_expect(self.loc) @@ -192,7 +201,7 @@ class _InputWithContainer(_InputBase): loc_container: Locator """ - `loc_container` is the locator of the container of the input. + `Locator` for the container of the input. """ def __init__( @@ -209,13 +218,13 @@ def __init__( Parameters ---------- page - The page where the input is located. + The Playwright `Page` of the Shiny app. id The id of the input. loc - The locator of the input. + The Playwright `Locator` of the input. loc_container - The locator of the container of the input. + The Playwright `Locator` of the container of the input. """ loc_is_str = isinstance(loc, str) loc_container_is_str = isinstance(loc_container, str) @@ -251,14 +260,6 @@ def __init__( class _InputWithLabel(_InputWithContainer): """A mixin class representing inputs with a label.""" - loc: Locator - """ - `loc` is the locator of the input. - """ - loc_container: Locator - """ - `loc_container` is the locator of the container of the input. - """ loc_label: Locator """ `loc_label` is the locator of the label of the input. @@ -283,11 +284,11 @@ def __init__( id The id of the input. loc - The locator of the input. + The Playwright `Locator` of the input. loc_container - The locator of the container of the input. + The Playwright `Locator` of the container of the input. loc_label - The locator of the label of the input. Defaults to `None`. + The Playwright `Locator` of the label of the input. Defaults to `None`. """ super().__init__( page, @@ -309,12 +310,12 @@ def expect_label( timeout: Timeout = None, ) -> None: """ - Expect the label of the input to have a specific value. + Expect the label of the input to have a specific text. Parameters ---------- value - The expected value of the label. + The expected text value of the label. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -323,8 +324,9 @@ def expect_label( class _WidthLocM: """ - A mixin class representing the `loc`'s width. - This class provides methods to expect the width attribute of an element. + A mixin class representing the `.loc`'s width. + + This class provides methods to expect the width attribute of a DOM element. """ def expect_width( @@ -334,12 +336,12 @@ def expect_width( timeout: Timeout = None, ) -> None: """ - Expect the width attribute of an element to have a specific value. + Expect the `width` attribute of a DOM element to have a specific value. Parameters ---------- value - The expected value of the width attribute. + The expected value of the `width` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -349,7 +351,8 @@ def expect_width( class _WidthContainerM: """ A mixin class representing the container's width. - This class provides methods to expect the width attribute of an element's container. + + This class provides methods to expect the width attribute of a DOM element's container. """ def expect_width( @@ -359,12 +362,12 @@ def expect_width( timeout: Timeout = None, ) -> None: """ - Expect the width attribute of an element's container to have a specific value. + Expect the `width` attribute of a input's container to have a specific value. Parameters ---------- value - The expected value of the width attribute. + The expected value of the `width` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -376,7 +379,7 @@ def expect_width( class _SetTextM: def set(self: _InputBaseP, value: str, *, timeout: Timeout = None) -> None: """ - Sets the text of the input. + Sets the text value Parameters ---------- @@ -389,7 +392,7 @@ def set(self: _InputBaseP, value: str, *, timeout: Timeout = None) -> None: class _ExpectTextInputValueM: - """A mixin class representing text input values.""" + """A mixin class for text input values.""" def expect_value( self: _InputBaseP, @@ -416,11 +419,11 @@ class InputNumeric( _WidthLocM, _InputWithLabel, ): - """Input numeric control for :func: `~shiny.ui.input_numeric`""" + """Input numeric control for :func:`~shiny.ui.input_numeric`""" def __init__(self, page: Page, id: str) -> None: """ - Initializes the input numeric. + Initializes the input numeric Playwright control. Parameters ---------- @@ -442,12 +445,12 @@ def expect_min( timeout: Timeout = None, ) -> None: """ - Expect the min attribute of the input to have a specific value. + Expect the minimum numeric value to be a specific value. Parameters ---------- value - The expected value of the min attribute. + The expected minimum numeric value. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -460,12 +463,12 @@ def expect_max( timeout: Timeout = None, ) -> None: """ - Expect the max attribute of the input to have a specific value. + Expect the maximum numeric value to be a specific value. Parameters ---------- value - The expected value of the max attribute. + The expected maximum numeric value. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -478,12 +481,12 @@ def expect_step( timeout: Timeout = None, ) -> None: """ - Expect the step attribute of the input to have a specific value. + Expect step value when incrementing/decrementing the numeric input. Parameters ---------- value - The expected value of the step attribute. + The expected step value for the numeric input. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -491,6 +494,10 @@ def expect_step( class _ExpectSpellcheckAttrM: + """ + A mixin class for the spellcheck attribute. + """ + def expect_spellcheck( self: _InputBaseP, value: Literal["true", "false"] | None, @@ -498,12 +505,12 @@ def expect_spellcheck( timeout: Timeout = None, ) -> None: """ - Expect the spellcheck attribute of the input to have a specific value. + Expect the `spellcheck` attribute of the input to have a specific value. Parameters ---------- value - The expected value of the spellcheck attribute. + The expected value of the `spellcheck` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -521,12 +528,12 @@ def expect_placeholder( timeout: Timeout = None, ) -> None: """ - Expect the placeholder attribute of the input to have a specific value. + Expect the `placeholder` attribute of the input to have a specific value. Parameters ---------- value - The expected value of the placeholder attribute. + The expected value of the `placeholder` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -543,12 +550,12 @@ def expect_autocomplete( timeout: Timeout = None, ) -> None: """ - Expect the autocomplete attribute of the input to have a specific value. + Expect the `autocomplete` attribute of the input to have a specific value. Parameters ---------- value - The expected value of the autocomplete attribute. + The expected value of the `autocomplete` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -566,19 +573,15 @@ class InputText( _ExpectSpellcheckAttrM, _InputWithLabel, ): - """Input text control for :func: `~shiny.ui.input_text`""" + """Input text control for :func:`~shiny.ui.input_text`""" - loc: Locator - """ - The locator of the input. - """ loc_container: Locator """ - The locator of the container of the input. + The Playwright `Locator` of the container of the input. """ loc_label: Locator """ - The locator of the label of the input. + The Playwright `Locator` of the label of the input. """ def __init__(self, page: Page, id: str) -> None: @@ -605,13 +608,7 @@ class InputPassword( _ExpectPlaceholderAttrM, _InputWithLabel, ): - """Input password control for :func: `~shiny.ui.input_password`""" - - loc: Locator - """ - The locator of the input. - """ - ... + """Input password control for :func:`~shiny.ui.input_password`""" def __init__(self, page: Page, id: str) -> None: """ @@ -639,12 +636,12 @@ def expect_width( timeout: Timeout = None, ) -> None: """ - Expect the width attribute of the input password to have a specific value. + Expect the `width` attribute of the input password to have a specific value. Parameters ---------- value - The expected value of the width attribute. + The expected value of the `width` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -662,12 +659,7 @@ class InputTextArea( _ExpectSpellcheckAttrM, _InputWithLabel, ): - """Input text area control for :func: `~shiny.ui.input_text_area`""" - - loc: Locator - """ - The locator of the input. - """ + """Input text area control for :func:`~shiny.ui.input_text_area`""" def __init__(self, page: Page, id: str) -> None: """ @@ -688,12 +680,12 @@ def __init__(self, page: Page, id: str) -> None: def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: """ - Expect the width attribute of the input text area to have a specific value. + Expect the `width` attribute of the input text area to have a specific value. Parameters ---------- value - The expected value of the width attribute. + The expected value of the `width` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -706,12 +698,12 @@ def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: """ - Expect the height attribute of the input text area to have a specific value. + Expect the `height` attribute of the input text area to have a specific value. Parameters ---------- value - The expected value of the height attribute. + The expected value of the `height` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -719,12 +711,12 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: def expect_cols(self, value: AttrValue, *, timeout: Timeout = None) -> None: """ - Expect the cols attribute of the input text area to have a specific value. + Expect the `cols` attribute of the input text area to have a specific value. Parameters ---------- value - The expected value of the cols attribute. + The expected value of the `cols` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -732,12 +724,12 @@ def expect_cols(self, value: AttrValue, *, timeout: Timeout = None) -> None: def expect_rows(self, value: AttrValue, *, timeout: Timeout = None) -> None: """ - Expect the rows attribute of the input text area to have a specific value. + Expect the `rows` attribute of the input text area to have a specific value. Parameters ---------- value - The expected value of the rows attribute. + The expected value of the `rows` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -750,12 +742,12 @@ def expect_resize( timeout: Timeout = None, ) -> None: """ - Expect the resize attribute of the input text area to have a specific value. + Expect the `resize` attribute of the input text area to have a specific value. Parameters ---------- value - The expected value of the resize attribute. + The expected value of the `resize` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -768,12 +760,12 @@ def expect_autoresize( timeout: Timeout = None, ) -> None: """ - Expect the autoresize attribute of the input text area to have a specific value. + Expect the `autoresize` attribute of the input text area to have a specific value. Parameters ---------- value - The expected value of the autoresize attribute. + The expected value of the `autoresize` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -858,7 +850,7 @@ def expect_choices( timeout: Timeout = None, ) -> None: """ - Expect the choices of the input select to be in order. + Expect the available options of the input select to be an exact match. Parameters ---------- @@ -867,7 +859,7 @@ def expect_choices( timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ - """Expect choices to be in order""" + # Playwright doesn't like lists of size 0. Instead, check for empty locator if len(choices) == 0: playwright_expect(self.loc_choices).to_have_count(0, timeout=timeout) @@ -889,7 +881,7 @@ def expect_selected( timeout: Timeout = None, ) -> None: """ - Expect the selected option(s) of the input select to be in order. + Expect the selected option(s) of the input select to be an exact match. Parameters ---------- @@ -898,7 +890,6 @@ def expect_selected( timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ - """Expect choices to be in order""" # Playwright doesn't like lists of size 0 if isinstance(selected, list) and len(selected) == 0: playwright_expect(self.loc_selected).to_have_count(0, timeout=timeout) @@ -927,7 +918,7 @@ def expect_choice_groups( timeout: Timeout = None, ) -> None: """ - Expect the choice groups of the input select to be in order. + Expect the choice groups of the input select to be an exact match. Parameters ---------- @@ -936,7 +927,7 @@ def expect_choice_groups( timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ - """Expect choices to be in order""" + # Playwright doesn't like lists of size 0. Instead, use `None` if len(choice_groups) == 0: playwright_expect(self.loc_choice_groups).to_have_count(0, timeout=timeout) @@ -959,7 +950,7 @@ def expect_choice_labels( timeout: Timeout = None, ) -> None: """ - Expect the choice labels of the input select to be in order. + Expect the choice labels of the input select to be an exact match. Parameters ---------- @@ -995,7 +986,7 @@ def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- value - The expected value of the size attribute. + The expected value of the `size` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -1008,7 +999,7 @@ def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: class InputSelect(_InputSelectBase): - """Input select control for :func: `~shiny.ui.input_select`""" + """Input select control for :func:`~shiny.ui.input_select`""" def __init__(self, page: Page, id: str) -> None: """ @@ -1049,7 +1040,7 @@ def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: class InputSelectize(_InputSelectBase): - """Input selectize control for :func: `~shiny.ui.input_selectize`""" + """Input selectize control for :func:`~shiny.ui.input_selectize`""" def __init__(self, page: Page, id: str) -> None: super().__init__( @@ -1066,7 +1057,18 @@ def expect_label( *, timeout: Timeout = None, ) -> None: - """Must include icon if present""" + """ + Expect the label of the input button to have a specific value. + + Note: This must include the icon if it is present! + + Parameters + ---------- + value + The expected value of the label. + timeout + The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. + """ self.expect.to_have_text(value, timeout=timeout) @@ -1086,7 +1088,7 @@ class InputActionButton( _WidthLocM, _InputActionBase, ): - """Input action button control for :func: `~shiny.ui.input_action_button`""" + """Input action button control for :func:`~shiny.ui.input_action_button`""" def __init__( self, @@ -1111,7 +1113,7 @@ def __init__( class InputDarkMode(_InputBase): - """Input dark mode control for :func: `~shiny.ui.input_dark_mode`""" + """Input dark mode control for :func:`~shiny.ui.input_dark_mode`""" def __init__( self, @@ -1150,12 +1152,12 @@ def click(self, *, timeout: Timeout = None): def expect_mode(self, value: str, *, timeout: Timeout = None): """ - Expect the mode attribute of the input dark mode to have a specific value. + Expect the `mode` attribute of the input dark mode to have a specific value. Parameters ---------- value - The expected value of the mode attribute. + The expected value of the `mode` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -1165,12 +1167,12 @@ def expect_mode(self, value: str, *, timeout: Timeout = None): def expect_page_mode(self, value: str, *, timeout: Timeout = None): """ - Expect the page mode to have a specific value. + Expect the page to have a specific dark mode value. Parameters ---------- value - The expected value of the page mode. + The expected value of the page's dark mode. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -1181,12 +1183,12 @@ def expect_page_mode(self, value: str, *, timeout: Timeout = None): def expect_wc_attribute(self, value: str, *, timeout: Timeout = None): """ - Expect the wc attribute of the input dark mode to have a specific value. + Expect the `wc` attribute of the input dark mode to have a specific value. Parameters ---------- value - The expected value of the wc attribute. + The expected value of the `wc` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -1200,12 +1202,7 @@ class InputTaskButton( _WidthLocM, _InputActionBase, ): - """Input task button control for :func: `~shiny.ui.input_task_button`""" - - loc: Locator - """ - The locator of the input task button. - """ + """Input task button control for :func:`~shiny.ui.input_task_button`""" # TODO-Karan: Test auto_reset functionality def __init__( @@ -1238,7 +1235,7 @@ def expect_state( Parameters ---------- value - The expected value of the state. + The expected value of the state of the input task button. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -1264,7 +1261,7 @@ def expect_label(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: def expect_label_ready(self, value: PatternOrStr, *, timeout: Timeout = None): """ - Expect the label of the input task button to have a specific value. + Expect the label of a ready input task button to have a specific value. Parameters ---------- @@ -1277,7 +1274,7 @@ def expect_label_ready(self, value: PatternOrStr, *, timeout: Timeout = None): def expect_label_busy(self, value: PatternOrStr, *, timeout: Timeout = None): """ - Expect the label of the input task button to have a specific value. + Expect the label of a busy input task button to have a specific value. Parameters ---------- @@ -1292,7 +1289,7 @@ def expect_label_state( self, state: str, value: PatternOrStr, *, timeout: Timeout = None ): """ - Expect the label of the input task button to have a specific value. + Expect the label of the input task button to have a specific value in a specific state. Parameters ---------- @@ -1309,12 +1306,12 @@ def expect_label_state( def expect_auto_reset(self, value: bool, timeout: Timeout = None): """ - Expect the auto-reset attribute of the input task button to have a specific value. + Expect the `auto-reset` attribute of the input task button to have a specific value. Parameters ---------- value - The expected value of the auto-reset attribute. + The expected value of the `auto-reset` attribute. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -1327,12 +1324,7 @@ def expect_auto_reset(self, value: bool, timeout: Timeout = None): class InputActionLink(_InputActionBase): - """Input action link control for :func: `~shiny.ui.input_action_link`""" - - loc: Locator - """ - The locator of the input action link. - """ + """Input action link control for :func:`~shiny.ui.input_action_link`""" def __init__( self, @@ -1378,9 +1370,9 @@ def __init__( id The id of the input checkbox. loc - The locator of the input checkbox. + The Playwright `Locator` of the input checkbox. loc_label - The locator of the label of the input checkbox. + The Playwright `Locator` of the label of the input checkbox. """ super().__init__( page, @@ -1437,20 +1429,7 @@ def expect_checked(self, value: bool, *, timeout: Timeout = None) -> None: class InputCheckbox(_InputCheckboxBase): - """Input checkbox control for :func: `~shiny.ui.input_checkbox`""" - - loc: Locator - """ - The locator of the input checkbox. - """ - loc_container: Locator - """ - The locator of the container of the input checkbox. - """ - loc_label: Locator - """ - The locator of the label of the input checkbox. - """ + """Input checkbox control for :func:`~shiny.ui.input_checkbox`""" def __init__( self, @@ -1476,20 +1455,7 @@ def __init__( class InputSwitch(_InputCheckboxBase): - """Input switch control for :func: `~shiny.ui.input_switch`""" - - loc: Locator - """ - The locator of the input switch. - """ - loc_container: Locator - """ - The locator of the container of the input switch. - """ - loc_label: Locator - """ - The locator of the label of the input switch. - """ + """Input switch control for :func:`~shiny.ui.input_switch`""" def __init__( self, @@ -1525,9 +1491,9 @@ def assert_arr_is_unique( Parameters ---------- - arr : ListPatternOrStr + arr The array to check. - msg : str + msg The error message. """ assert len(arr) == len(list(dict.fromkeys(arr))), msg @@ -1541,7 +1507,7 @@ def checked_css_str( Parameters ---------- - is_checked : bool | MISSING_TYPE, optional + is_checked Whether the elements are checked, by default MISSING """ if is_missing(is_checked): @@ -1567,23 +1533,26 @@ def expect_locator_contains_values_in_list( """ Expect the locator to contain the values in the list. + The matching values must exist and be in order, but other values may also exist + within the container. + Parameters ---------- - page : Page + page The Playwright page. - loc_container : Locator + loc_container The container locator. - el_type : str + el_type The element type. - arr_name : str - The array name. - arr : list[str] + arr_name + The variable name. + arr The expected values. - is_checked : bool | MISSING_TYPE, optional + is_checked Whether the elements are checked, by default MISSING - timeout : Timeout, optional + timeout The timeout for the expectation, by default None - key : str, optional + key The key, by default "value" """ # Make sure the locator contains all of `arr` @@ -1652,23 +1621,26 @@ def expect_locator_values_in_list( """ Expect the locator to contain the values in the list. + The matching values must exist and be in order. No other matching values will be + allowed within the container. + Parameters ---------- - page : Page + page The Playwright page. - loc_container : Locator + loc_container The container locator. - el_type : Locator | str + el_type The element type locator. - arr_name : str + arr_name The array name. - arr : ListPatternOrStr + arr The expected values. - is_checked : bool | MISSING_TYPE, optional + is_checked Whether the elements are checked, by default MISSING - timeout : Timeout, optional + timeout The timeout for the expectation, by default None - key : str, optional + key The key, by default "value" """ # Make sure the locator has exactly `arr` values @@ -1753,9 +1725,9 @@ def expect_choice_labels( Parameters ---------- - labels : ListPatternOrStr + labels The expected labels. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ if len(labels) == 1: @@ -1773,9 +1745,9 @@ def expect_inline(self, inline: bool, *, timeout: Timeout = None) -> None: Parameters ---------- - inline : bool + inline Whether the input is inline. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ _expect_class_value( @@ -1805,9 +1777,9 @@ def __init__( Parameters ---------- - page : Page + page The Playwright page. - id : str + id The id of the checkbox group. """ super().__init__( @@ -1850,9 +1822,9 @@ def set( Parameters ---------- - selected : list[str] + selected The values of the selected checkboxes. - timeout : Timeout, optional + timeout The timeout for the action, by default None. """ # Having an arr of size 0 is allowed. Will uncheck everything @@ -1902,9 +1874,9 @@ def expect_choices( Parameters ---------- - choices : ListPatternOrStr + choices The expected choices. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ _MultipleDomItems.expect_locator_values_in_list( @@ -1927,9 +1899,9 @@ def expect_selected( Parameters ---------- - selected : ListPatternOrStr + selected The expected values of the selected checkboxes. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ # Playwright doesn't like lists of size 0 @@ -1952,19 +1924,19 @@ class InputRadioButtons( _WidthContainerM, _RadioButtonCheckboxGroupBase, ): - """Input radio buttons control for :func: `~shiny.ui.input_radio_buttons`""" + """Input radio buttons control for :func:`~shiny.ui.input_radio_buttons`""" loc_selected: Locator """ - The locator of the selected radio button. + The Playwright `Locator` of the selected radio button. """ loc_choices: Locator """ - The locator of the radio button choices. + The Playwright `Locator` of the radio button choices. """ loc_choice_labels: Locator """ - The locator of the labels of the radio button choices. + The Playwright `Locator` of the labels of the radio button choices. """ def __init__( @@ -1976,9 +1948,9 @@ def __init__( Parameters ---------- - page : Page + page The Playwright page. - id : str + id The id of the radio buttons. """ super().__init__( @@ -2020,9 +1992,9 @@ def set( Parameters ---------- - selected : str + selected The value of the selected radio button. - timeout : Timeout, optional + timeout The timeout for the action, by default None. """ assert_type(selected, str) @@ -2043,9 +2015,9 @@ def expect_choices( Parameters ---------- - choices : ListPatternOrStr + choices The expected choices. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ _MultipleDomItems.expect_locator_values_in_list( @@ -2068,9 +2040,9 @@ def expect_selected( Parameters ---------- - selected : PatternOrStr | None + selected The expected value of the selected radio button. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ # Playwright doesn't like lists of size 0. Instead, use `None` @@ -2085,19 +2057,19 @@ class InputFile( # _ExpectPlaceholderAttrM, _InputWithLabel, ): - """Input file control for :func: `~shiny.ui.input_file`""" + """Input file control for :func:`~shiny.ui.input_file`""" loc_button: Locator """ - The locator of the button. + The Playwright `Locator` of the button. """ loc_file_display: Locator """ - The locator of the file display. + The Playwright `Locator` of the file display. """ loc_progress: Locator """ - The locator of the progress bar. + The Playwright `Locator` of the progress bar. """ # id: str, @@ -2123,9 +2095,9 @@ def __init__( Parameters ---------- - page : Page + page The Playwright page. - id : str + id The id of the file input. """ super().__init__( @@ -2155,11 +2127,11 @@ def set( Parameters ---------- - file_path : str | pathlib.Path | FilePayload | list[str | pathlib.Path] | list[FilePayload] + file_path The path to the file to upload. - timeout : Timeout, optional + timeout The timeout for the action, by default None. - expect_complete_timeout : Timeout, optional + expect_complete_timeout The timeout for the expectation that the upload is complete, by default 30 * 1000. """ self.loc.wait_for(state="visible", timeout=timeout) @@ -2179,7 +2151,7 @@ def expect_complete( Parameters ---------- - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_to_have_style(self.loc_progress, "width", "100%", timeout=timeout) @@ -2199,9 +2171,9 @@ def expect_accept( Parameters ---------- - accept : list[str] | AttrValue + accept The expected value of the `accept` attribute. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ if isinstance(accept, list): @@ -2222,9 +2194,9 @@ def expect_button_label( Parameters ---------- - button_label : PatternOrStr + button_label The expected value of the button label. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ playwright_expect(self.loc_button).to_have_text(button_label, timeout=timeout) @@ -2240,9 +2212,9 @@ def expect_capture( Parameters ---------- - capture : Literal["environment", "user"] | None + capture The expected value of the `capture` attribute. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value(self.loc, "capture", capture, timeout=timeout) @@ -2257,15 +2229,15 @@ class _InputSliderBase(_WidthLocM, _InputWithLabel): loc_irs: Locator """ - The locator of the input slider. + The Playwright `Locator` of the input slider. """ loc_irs_ticks: Locator """ - The locator of the input slider ticks. + The Playwright `Locator` of the input slider ticks. """ loc_play_pause: Locator """ - The locator of the play/pause button. + The Playwright `Locator` of the play/pause button. """ def __init__( @@ -2278,9 +2250,9 @@ def __init__( Parameters ---------- - page : Page + page The Playwright page. - id : str + id The id of the slider. """ super().__init__( @@ -2305,9 +2277,9 @@ def expect_tick_labels( Parameters ---------- - value : ListPatternOrStr | None + value The expected tick labels. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ if value is None: @@ -2322,9 +2294,9 @@ def expect_animate(self, exists: bool, *, timeout: Timeout = None) -> None: Parameters ---------- - exists : bool + exists Whether the animate button should exist. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ animate_count = 1 if exists else 0 @@ -2367,7 +2339,7 @@ def click_play(self, *, timeout: Timeout = None) -> None: Parameters ---------- - timeout : Timeout, optional + timeout The timeout for the action, by default None. """ self.loc_container.wait_for(state="visible", timeout=timeout) @@ -2383,7 +2355,7 @@ def click_pause(self, *, timeout: Timeout = None) -> None: Parameters ---------- - timeout : Timeout, optional + timeout The timeout for the action, by default None. """ self.loc_container.wait_for(state="visible", timeout=timeout) @@ -2399,9 +2371,9 @@ def expect_min(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2414,9 +2386,9 @@ def expect_max(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2429,9 +2401,9 @@ def expect_step(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2444,9 +2416,9 @@ def expect_ticks(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2459,9 +2431,9 @@ def expect_sep(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2474,9 +2446,9 @@ def expect_pre(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2489,9 +2461,9 @@ def expect_post(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Timeout, optional + timeout The timeout for the expectation, by default None. """ expect_attribute_to_have_value( @@ -2509,9 +2481,9 @@ def expect_time_format(self, value: AttrValue, *, timeout: Timeout = None) -> No Parameters ---------- - value : AttrValue + value The expected value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -2524,9 +2496,9 @@ def expect_timezone(self, value: AttrValue, *, timeout: Timeout = None) -> None: Parameters ---------- - value : AttrValue + value The expected value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -2539,9 +2511,9 @@ def expect_drag_range(self, value: AttrValue, *, timeout: Timeout = None) -> Non Parameters ---------- - value : AttrValue + value The expected value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -2597,11 +2569,11 @@ def slow_move(x: float, y: float, delay: float = sleep_time) -> None: Parameters ---------- - x : float + x The x-coordinate. - y : float + y The y-coordinate. - delay : float, optional + delay The delay between each move, by default sleep_time. """ mouse.move(x, y) @@ -2672,11 +2644,11 @@ def _handle_center( class InputSlider(_InputSliderBase): - """Input slider control for :func: `~shiny.ui.input_slider`""" + """Input slider control for :func:`~shiny.ui.input_slider`""" loc_irs_label: Locator """ - The locator of the input slider label. + The Playwright `Locator` of the input slider label. """ def __init__( @@ -2689,9 +2661,9 @@ def __init__( Parameters ---------- - page : Page + page The Playwright Page object. - id : str + id The id of the input element. """ super().__init__(page, id=id) @@ -2703,9 +2675,9 @@ def expect_value(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: Parameters ---------- - value : PatternOrStr + value The expected value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ playwright_expect(self.loc_irs_label).to_have_text(value, timeout=timeout) @@ -2722,11 +2694,11 @@ def set( Parameters ---------- - value : str + value The value to set the slider to. - max_err_values : int, optional + max_err_values The maximum number of error values to display if the value is not found. Defaults to 15. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ self._wait_for_container(timeout=timeout) @@ -2747,15 +2719,15 @@ def set( class InputSliderRange(_InputSliderBase): - """Input slider range control for :func: `~shiny.ui.input_slider_range`""" + """Input slider range control for :func:`~shiny.ui.input_slider_range`""" loc_irs_label_from: Locator """ - The locator of the input slider label for the `from` handle. + The Playwright `Locator` of the input slider label for the `from` handle. """ loc_irs_label_to: Locator """ - The locator of the input slider label for the `to` handle. + The Playwright `Locator` of the input slider label for the `to` handle. """ def __init__( @@ -2768,9 +2740,9 @@ def __init__( Parameters ---------- - page : Page + page The Playwright Page object. - id : str + id The id of the input element. """ super().__init__(page, id=id) @@ -2792,9 +2764,9 @@ def expect_value( Parameters ---------- - value : Tuple[PatternOrStr, PatternOrStr] + value The expected value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ if all_missing(*value): @@ -2850,11 +2822,11 @@ def set( Parameters ---------- - value : Tuple[str, str] | Tuple[str, MISSING_TYPE] | Tuple[MISSING_TYPE, str] + value The value to set the slider to. - max_err_values : int, optional + max_err_values The maximum number of error values to display if the value is not found. Defaults to 15. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ if all_missing(*value): @@ -2930,9 +2902,9 @@ def expect_value( Parameters ---------- - value : PatternOrStr + value The expected value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ # if value is None: @@ -2951,9 +2923,9 @@ def expect_min_date( Parameters ---------- - value : str + value The expected `data-min-date` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -2971,9 +2943,9 @@ def expect_max_date( Parameters ---------- - value : str + value The expected `data-max-date` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -2991,9 +2963,9 @@ def expect_format( Parameters ---------- - value : str + value The expected `data-date-format` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -3011,9 +2983,9 @@ def expect_startview( Parameters ---------- - value : str + value The expected `data-date-start-view` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -3031,9 +3003,9 @@ def expect_weekstart( Parameters ---------- - value : int + value The expected `data-date-week-start` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ if isinstance(value, int): @@ -3053,9 +3025,9 @@ def expect_language( Parameters ---------- - value : str + value The expected `data-date-language` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -3074,9 +3046,9 @@ def expect_autoclose( Parameters ---------- - value : Literal["true", "false"] + value The expected `data-date-autoclose` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ expect_attribute_to_have_value( @@ -3094,9 +3066,9 @@ def expect_datesdisabled( Parameters ---------- - value : Optional[list[str]] + value The expected `data-date-dates-disabled` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ if isinstance(value, list): @@ -3120,9 +3092,9 @@ def expect_daysofweekdisabled( Parameters ---------- - value : Optional[list[int]] + value The expected `data-date-days-of-week-disabled` attribute value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ if isinstance(value, list): @@ -3143,9 +3115,9 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- - page : Page + page The page object. - id : str + id The id of the input element. """ super().__init__( @@ -3157,19 +3129,19 @@ def __init__(self, page: Page, id: str) -> None: class InputDateRange(_WidthContainerM, _InputWithLabel): - """Input date range control for :func: `~shiny.ui.input_date_range`""" + """Input date range control for :func:`~shiny.ui.input_date_range`""" loc_separator: Locator """ - The locator of the separator between the two input elements. + The Playwright `Locator` of the separator between the two input elements. """ loc_start: Locator """ - The locator of the start date input element. + The Playwright `Locator` of the start date input element. """ loc_end: Locator """ - The locator of the end date input element. + The Playwright `Locator` of the end date input element. """ date_start: _DateBase """ @@ -3186,9 +3158,9 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- - page : Page + page The page object. - id : str + id The id of the input element. """ super().__init__( @@ -3229,9 +3201,9 @@ def set( Parameters ---------- - value : Tuple[str, str] + value The value to set. The first element is the start date and the second element is the end date. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to be set. Defaults to `None`. """ start = value[0] @@ -3257,9 +3229,9 @@ def expect_value( Parameters ---------- - value : Tuple[PatternOrStr, PatternOrStr] + value The expected value. The first element is the start date and the second element is the end date. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ if all_missing(*value): @@ -3287,9 +3259,9 @@ def expect_min_date( Parameters ---------- - value : AttrValue + value The expected minimum date. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the minimum date to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3308,9 +3280,9 @@ def expect_max_date( Parameters ---------- - value : AttrValue + value The expected maximum date. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the maximum date to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3329,9 +3301,9 @@ def expect_format( Parameters ---------- - value : AttrValue + value The expected format. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the format to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3350,9 +3322,9 @@ def expect_startview( Parameters ---------- - value : AttrValue + value The expected start view. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the start view to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3371,9 +3343,9 @@ def expect_weekstart( Parameters ---------- - value : int + value The expected week start. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the week start to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3392,9 +3364,9 @@ def expect_language( Parameters ---------- - value : AttrValue + value The expected language. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the language to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3413,9 +3385,9 @@ def expect_separator( Parameters ---------- - value : PatternOrStr + value The expected separator. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the separator to appear. Defaults to `None`. """ playwright_expect(self.loc_separator).to_have_text(value, timeout=timeout) @@ -3434,9 +3406,9 @@ def expect_autoclose( Parameters ---------- - value : Literal["true", "false"] + value The expected autoclose value. - timeout : Optional[Union[int, float]] + timeout The maximum time to wait for the value to appear. Defaults to `None`. """ # TODO-future; Composable expectations @@ -3456,9 +3428,22 @@ class _OutputBaseP(Protocol): class _OutputBase: + """ + Base class for output controls. + """ + id: str + """ + The ID of the output control. + """ loc: Locator + """ + The Playwright `Locator` of the output control. + """ page: Page + """ + The Playwright `Page` of the Shiny app. + """ def __init__( self, @@ -3552,12 +3537,15 @@ def expect_inline( self.expect_container_tag(tag_name, timeout=timeout) -class OutputText(_OutputInlineContainerM, _OutputTextValue): - """Text output control for :func: `~shiny.ui.text_output`""" +class OutputText( + _OutputInlineContainerM, + _OutputTextValue, +): + """Text output control for :func:`~shiny.ui.text_output`""" loc: Locator """ - The locator of the text output. + The Playwright `Locator` of the text output. """ def __init__( @@ -3590,11 +3578,11 @@ def get_value(self, *, timeout: Timeout = None) -> str: class OutputCode(_OutputTextValue): - """Code output control for :func: `~shiny.ui.code_output`""" + """Code output control for :func:`~shiny.ui.code_output`""" loc: Locator """ - The locator of the code output. + The Playwright `Locator` of the code output. """ def __init__(self, page: Page, id: str) -> None: @@ -3632,11 +3620,11 @@ def expect_has_placeholder( class OutputTextVerbatim(_OutputTextValue): - """Verbatim text output control for :func: `~shiny.ui.text_output_verbatim`""" + """Verbatim text output control for :func:`~shiny.ui.text_output_verbatim`""" loc: Locator """ - The locator of the verbatim text output. + The Playwright `Locator` of the verbatim text output. """ def __init__(self, page: Page, id: str) -> None: @@ -3667,7 +3655,7 @@ class _OutputImageBase(_OutputInlineContainerM, _OutputBase): loc_img: Locator """ - The locator of the image. + The Playwright `Locator` of the image. """ def __init__(self, page: Page, id: str, loc_classes: str = "") -> None: @@ -3823,11 +3811,11 @@ def __init__(self, page: Page, id: str) -> None: class OutputPlot(_OutputImageBase): - """Plot output control for :func: `~shiny.ui.plot_output`""" + """Plot output control for :func:`~shiny.ui.plot_output`""" loc: Locator """ - The locator of the plot output. + The Playwright `Locator` of the plot output. """ def __init__(self, page: Page, id: str) -> None: @@ -3845,12 +3833,7 @@ def __init__(self, page: Page, id: str) -> None: class OutputUi(_OutputInlineContainerM, _OutputBase): - """UI output control for :func: `~shiny.ui.ui_output`""" - - loc: Locator - """ - The locator of the UI output. - """ + """UI output control for :func:`~shiny.ui.ui_output`""" def __init__(self, page: Page, id: str) -> None: """ @@ -3878,12 +3861,7 @@ def expect_text(self, text: str, *, timeout: Timeout = None) -> None: # When making selectors, use `xpath` so that direct decendents can be checked class OutputTable(_OutputBase): - """Table output control for :func: `~shiny.ui.table_output`""" - - loc: Locator - """ - The locator of the table output. - """ + """Table output control for :func:`~shiny.ui.table_output`""" def __init__(self, page: Page, id: str) -> None: """ @@ -4042,15 +4020,15 @@ class Sidebar( """ loc: Locator """ - The locator for the sidebar. + The Playwright `Locator` for the sidebar. """ loc_handle: Locator """ - The locator for the handle of the sidebar. + The Playwright `Locator` for the handle of the sidebar. """ loc_position: Locator """ - The locator for the position of the sidebar. + The Playwright `Locator` for the position of the sidebar. """ def __init__(self, page: Page, id: str) -> None: @@ -4170,7 +4148,7 @@ class _CardBodyP(_InputBaseP, Protocol): loc_body: Locator """ - The locator for the body element of the card control. + The Playwright `Locator` for the body element of the card control. """ @@ -4205,7 +4183,7 @@ class _CardFooterLayoutP(_InputBaseP, Protocol): loc_footer: Locator """ - The locator for the footer element. + The Playwright `Locator` for the footer element. """ @@ -4243,15 +4221,15 @@ class _CardFullScreenLayoutP(_OutputBaseP, Protocol): loc_title: Locator """ - The locator for the title element. + The Playwright `Locator` for the title element. """ _loc_fullscreen: Locator """ - The locator for the full-screen element. + The Playwright `Locator` for the full-screen element. """ _loc_close_button: Locator """ - The locator for the close button element. + The Playwright `Locator` for the close button element. """ @@ -4953,11 +4931,11 @@ def __init__( Parameters ---------- page - The Playwright page object. + The Playwright `Page` object. id The ID of the overlay. loc - The locator of the overlay. + The Playwright `Locator` of the overlay. overlay_name The name of the overlay. overlay_selector From c99dbc6e91211471f4f2dde89f3254bab28c2dcc Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Mon, 10 Jun 2024 10:52:13 -0400 Subject: [PATCH 08/11] Doc updates. Minor api changes --- shiny/playwright/controls/_controls.py | 579 +++++++++--------- .../components/card-input/test_card-input.py | 12 +- .../value_box/kitchensink/test_valuebox_ks.py | 6 +- .../value_box/smoke/test_valuebox.py | 6 +- .../card/kitchensink/test_card_ks.py | 8 +- .../shiny/experimental/card/test_card.py | 6 +- 6 files changed, 321 insertions(+), 296 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index e148873ab..a9d4981c7 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -1,5 +1,8 @@ """Facade classes for working with Shiny inputs/outputs in Playwright""" +# TODO-barret; Make all `expect_*(FOO)` values to be `expect_*(value)` +# TODO-barret; Rename `InputBase` and `InputWithContainer` to generic, not-tied-to-input names + from __future__ import annotations import json @@ -117,7 +120,7 @@ def set_text( Parameters ---------- loc - The Playwright `Locator` of the element. + Playwright `Locator` of the element. text The text to set. delay @@ -151,7 +154,7 @@ class _InputWithContainerP(_InputBaseP, Protocol): loc_container: Locator """ - `Locator` for the container of the input. + Playwright `Locator` for the container of the input. """ @@ -165,11 +168,11 @@ class _InputBase: """ loc: Locator """ - The Playwright `Locator` of the input. + Playwright `Locator` of the input. """ page: Page """ - The Playwright `Page` of the Shiny app. + Playwright `Page` of the Shiny app. """ def __init__( @@ -189,7 +192,7 @@ def __init__( @property # TODO; Can not publicly find `LocatorAssertions` in `playwright` def expect(self): - """Expectation method equivalent to `playwright.expect(self.loc)`""" + """Expectation method equivalent to `playwright.expect(self.loc)`.""" # TODO-karan-test: Search for `.loc)` and convert `expect(FOO.loc)` to `FOO.expect`. If we don't like the helper API, we should remove it. return playwright_expect(self.loc) @@ -201,7 +204,7 @@ class _InputWithContainer(_InputBase): loc_container: Locator """ - `Locator` for the container of the input. + Playwright `Locator` for the container of the input. """ def __init__( @@ -218,13 +221,13 @@ def __init__( Parameters ---------- page - The Playwright `Page` of the Shiny app. + Playwright `Page` of the Shiny app. id The id of the input. loc - The Playwright `Locator` of the input. + Playwright `Locator` of the input. loc_container - The Playwright `Locator` of the container of the input. + Playwright `Locator` of the container of the input. """ loc_is_str = isinstance(loc, str) loc_container_is_str = isinstance(loc_container, str) @@ -262,7 +265,7 @@ class _InputWithLabel(_InputWithContainer): loc_label: Locator """ - `loc_label` is the locator of the label of the input. + Playwright `Locator` for the label of the input. """ def __init__( @@ -284,11 +287,11 @@ def __init__( id The id of the input. loc - The Playwright `Locator` of the input. + Playwright `Locator` of the input. loc_container - The Playwright `Locator` of the container of the input. + Playwright `Locator` of the container of the input. loc_label - The Playwright `Locator` of the label of the input. Defaults to `None`. + Playwright `Locator` of the label of the input. Defaults to `None`. """ super().__init__( page, @@ -419,7 +422,7 @@ class InputNumeric( _WidthLocM, _InputWithLabel, ): - """Input numeric control for :func:`~shiny.ui.input_numeric`""" + """Input numeric control for :func:`~shiny.ui.input_numeric`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -573,16 +576,7 @@ class InputText( _ExpectSpellcheckAttrM, _InputWithLabel, ): - """Input text control for :func:`~shiny.ui.input_text`""" - - loc_container: Locator - """ - The Playwright `Locator` of the container of the input. - """ - loc_label: Locator - """ - The Playwright `Locator` of the label of the input. - """ + """Input text control for :func:`~shiny.ui.input_text`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -608,7 +602,7 @@ class InputPassword( _ExpectPlaceholderAttrM, _InputWithLabel, ): - """Input password control for :func:`~shiny.ui.input_password`""" + """Input password control for :func:`~shiny.ui.input_password`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -659,7 +653,7 @@ class InputTextArea( _ExpectSpellcheckAttrM, _InputWithLabel, ): - """Input text area control for :func:`~shiny.ui.input_text_area`""" + """Input text area control for :func:`~shiny.ui.input_text_area`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -783,15 +777,15 @@ class _InputSelectBase( ): loc_selected: Locator """ - `loc_selected` is the locator of the selected option of the input select. + Playwright `Locator` for the selected option of the input select. """ loc_choices: Locator """ - `loc_choices` is the locator of the choices of the input select. + Playwright `Locator` for the choices of the input select. """ loc_choice_groups: Locator """ - `loc_choice_groups` is the locator of the choice groups of the input select. + Playwright `Locator` for the choice groups of the input select. """ def __init__( @@ -999,7 +993,7 @@ def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: class InputSelect(_InputSelectBase): - """Input select control for :func:`~shiny.ui.input_select`""" + """Input select control for :func:`~shiny.ui.input_select`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -1040,7 +1034,7 @@ def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: class InputSelectize(_InputSelectBase): - """Input selectize control for :func:`~shiny.ui.input_selectize`""" + """Input selectize control for :func:`~shiny.ui.input_selectize`.""" def __init__(self, page: Page, id: str) -> None: super().__init__( @@ -1088,7 +1082,7 @@ class InputActionButton( _WidthLocM, _InputActionBase, ): - """Input action button control for :func:`~shiny.ui.input_action_button`""" + """Input action button control for :func:`~shiny.ui.input_action_button`.""" def __init__( self, @@ -1113,7 +1107,7 @@ def __init__( class InputDarkMode(_InputBase): - """Input dark mode control for :func:`~shiny.ui.input_dark_mode`""" + """Input dark mode control for :func:`~shiny.ui.input_dark_mode`.""" def __init__( self, @@ -1202,7 +1196,7 @@ class InputTaskButton( _WidthLocM, _InputActionBase, ): - """Input task button control for :func:`~shiny.ui.input_task_button`""" + """Input task button control for :func:`~shiny.ui.input_task_button`.""" # TODO-Karan: Test auto_reset functionality def __init__( @@ -1227,7 +1221,10 @@ def __init__( ) def expect_state( - self, value: Literal["ready", "busy"] | str, *, timeout: Timeout = None + self, + value: Literal["ready", "busy"] | str, + *, + timeout: Timeout = None, ): """ Expect the state of the input task button to have a specific value. @@ -1324,7 +1321,7 @@ def expect_auto_reset(self, value: bool, timeout: Timeout = None): class InputActionLink(_InputActionBase): - """Input action link control for :func:`~shiny.ui.input_action_link`""" + """Input action link control for :func:`~shiny.ui.input_action_link`.""" def __init__( self, @@ -1370,9 +1367,9 @@ def __init__( id The id of the input checkbox. loc - The Playwright `Locator` of the input checkbox. + Playwright `Locator` of the input checkbox. loc_label - The Playwright `Locator` of the label of the input checkbox. + Playwright `Locator` of the label of the input checkbox. """ super().__init__( page, @@ -1429,7 +1426,7 @@ def expect_checked(self, value: bool, *, timeout: Timeout = None) -> None: class InputCheckbox(_InputCheckboxBase): - """Input checkbox control for :func:`~shiny.ui.input_checkbox`""" + """Input checkbox control for :func:`~shiny.ui.input_checkbox`.""" def __init__( self, @@ -1455,7 +1452,7 @@ def __init__( class InputSwitch(_InputCheckboxBase): - """Input switch control for :func:`~shiny.ui.input_switch`""" + """Input switch control for :func:`~shiny.ui.input_switch`.""" def __init__( self, @@ -1508,7 +1505,7 @@ def checked_css_str( Parameters ---------- is_checked - Whether the elements are checked, by default MISSING + Whether the elements are checked. Defaults to `MISSING`. """ if is_missing(is_checked): return "" @@ -1539,7 +1536,7 @@ def expect_locator_contains_values_in_list( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. loc_container The container locator. el_type @@ -1549,11 +1546,11 @@ def expect_locator_contains_values_in_list( arr The expected values. is_checked - Whether the elements are checked, by default MISSING + Whether the elements are checked. Defaults to `MISSING`. timeout - The timeout for the expectation, by default None + The timeout for the expectation. Defaults to `None`. key - The key, by default "value" + The key. Defaults to `"value"`. """ # Make sure the locator contains all of `arr` @@ -1627,7 +1624,7 @@ def expect_locator_values_in_list( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. loc_container The container locator. el_type @@ -1637,11 +1634,11 @@ def expect_locator_values_in_list( arr The expected values. is_checked - Whether the elements are checked, by default MISSING + Whether the elements are checked. Defaults to `MISSING`. timeout - The timeout for the expectation, by default None + The timeout for the expectation. Defaults to `None`. key - The key, by default "value" + The key. Defaults to `"value"`. """ # Make sure the locator has exactly `arr` values @@ -1711,6 +1708,9 @@ def expect_locator_values_in_list( raise e +# TODO-barret; continue from here + + class _RadioButtonCheckboxGroupBase(_InputWithLabel): loc_choice_labels: Locator @@ -1728,7 +1728,7 @@ def expect_choice_labels( labels The expected labels. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ if len(labels) == 1: labels_val = labels[0] @@ -1748,7 +1748,7 @@ def expect_inline(self, inline: bool, *, timeout: Timeout = None) -> None: inline Whether the input is inline. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ _expect_class_value( self.loc_container, @@ -1778,7 +1778,7 @@ def __init__( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The id of the checkbox group. """ @@ -1825,7 +1825,7 @@ def set( selected The values of the selected checkboxes. timeout - The timeout for the action, by default None. + The timeout for the action. Defaults to `None`. """ # Having an arr of size 0 is allowed. Will uncheck everything assert_type(selected, typing.List[str]) @@ -1877,7 +1877,7 @@ def expect_choices( choices The expected choices. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, @@ -1902,7 +1902,7 @@ def expect_selected( selected The expected values of the selected checkboxes. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ # Playwright doesn't like lists of size 0 if len(selected) == 0: @@ -1924,19 +1924,19 @@ class InputRadioButtons( _WidthContainerM, _RadioButtonCheckboxGroupBase, ): - """Input radio buttons control for :func:`~shiny.ui.input_radio_buttons`""" + """Input radio buttons control for :func:`~shiny.ui.input_radio_buttons`.""" loc_selected: Locator """ - The Playwright `Locator` of the selected radio button. + Playwright `Locator` of the selected radio button. """ loc_choices: Locator """ - The Playwright `Locator` of the radio button choices. + Playwright `Locator` of the radio button choices. """ loc_choice_labels: Locator """ - The Playwright `Locator` of the labels of the radio button choices. + Playwright `Locator` of the labels of the radio button choices. """ def __init__( @@ -1949,7 +1949,7 @@ def __init__( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The id of the radio buttons. """ @@ -1995,7 +1995,7 @@ def set( selected The value of the selected radio button. timeout - The timeout for the action, by default None. + The timeout for the action. Defaults to `None`. """ assert_type(selected, str) # Only need to set. @@ -2018,7 +2018,7 @@ def expect_choices( choices The expected choices. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ _MultipleDomItems.expect_locator_values_in_list( page=self.page, @@ -2043,7 +2043,7 @@ def expect_selected( selected The expected value of the selected radio button. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ # Playwright doesn't like lists of size 0. Instead, use `None` if selected is None: @@ -2057,19 +2057,19 @@ class InputFile( # _ExpectPlaceholderAttrM, _InputWithLabel, ): - """Input file control for :func:`~shiny.ui.input_file`""" + """Input file control for :func:`~shiny.ui.input_file`.""" loc_button: Locator """ - The Playwright `Locator` of the button. + Playwright `Locator` of the button. """ loc_file_display: Locator """ - The Playwright `Locator` of the file display. + Playwright `Locator` of the file display. """ loc_progress: Locator """ - The Playwright `Locator` of the progress bar. + Playwright `Locator` of the progress bar. """ # id: str, @@ -2096,7 +2096,7 @@ def __init__( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The id of the file input. """ @@ -2130,9 +2130,9 @@ def set( file_path The path to the file to upload. timeout - The timeout for the action, by default None. + The timeout for the action. Defaults to `None`. expect_complete_timeout - The timeout for the expectation that the upload is complete, by default 30 * 1000. + The timeout for the expectation that the upload is complete. Defaults to `30 * 1000`. """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) @@ -2152,7 +2152,7 @@ def expect_complete( Parameters ---------- timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_to_have_style(self.loc_progress, "width", "100%", timeout=timeout) @@ -2174,7 +2174,7 @@ def expect_accept( accept The expected value of the `accept` attribute. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ if isinstance(accept, list): accept = ",".join(accept) @@ -2197,7 +2197,7 @@ def expect_button_label( button_label The expected value of the button label. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ playwright_expect(self.loc_button).to_have_text(button_label, timeout=timeout) @@ -2215,7 +2215,7 @@ def expect_capture( capture The expected value of the `capture` attribute. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value(self.loc, "capture", capture, timeout=timeout) @@ -2229,15 +2229,15 @@ class _InputSliderBase(_WidthLocM, _InputWithLabel): loc_irs: Locator """ - The Playwright `Locator` of the input slider. + Playwright `Locator` of the input slider. """ loc_irs_ticks: Locator """ - The Playwright `Locator` of the input slider ticks. + Playwright `Locator` of the input slider ticks. """ loc_play_pause: Locator """ - The Playwright `Locator` of the play/pause button. + Playwright `Locator` of the play/pause button. """ def __init__( @@ -2251,7 +2251,7 @@ def __init__( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The id of the slider. """ @@ -2280,7 +2280,7 @@ def expect_tick_labels( value The expected tick labels. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ if value is None: playwright_expect(self.loc_irs_ticks).to_have_count(0) @@ -2297,7 +2297,7 @@ def expect_animate(self, exists: bool, *, timeout: Timeout = None) -> None: exists Whether the animate button should exist. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ animate_count = 1 if exists else 0 playwright_expect(self.loc_play_pause).to_have_count(animate_count) @@ -2340,7 +2340,7 @@ def click_play(self, *, timeout: Timeout = None) -> None: Parameters ---------- timeout - The timeout for the action, by default None. + The timeout for the action. Defaults to `None`. """ self.loc_container.wait_for(state="visible", timeout=timeout) self.loc_container.scroll_into_view_if_needed(timeout=timeout) @@ -2356,7 +2356,7 @@ def click_pause(self, *, timeout: Timeout = None) -> None: Parameters ---------- timeout - The timeout for the action, by default None. + The timeout for the action. Defaults to `None`. """ self.loc_container.wait_for(state="visible", timeout=timeout) self.loc_container.scroll_into_view_if_needed(timeout=timeout) @@ -2374,7 +2374,7 @@ def expect_min(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-min", value=value, timeout=timeout @@ -2389,7 +2389,7 @@ def expect_max(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-max", value=value, timeout=timeout @@ -2404,7 +2404,7 @@ def expect_step(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-step", value=value, timeout=timeout @@ -2419,7 +2419,7 @@ def expect_ticks(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-grid", value=value, timeout=timeout @@ -2434,7 +2434,7 @@ def expect_sep(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-prettify-separator", value=value, timeout=timeout @@ -2449,7 +2449,7 @@ def expect_pre(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-prefix", value=value, timeout=timeout @@ -2464,7 +2464,7 @@ def expect_post(self, value: AttrValue, *, timeout: Timeout = None) -> None: value The expected value. timeout - The timeout for the expectation, by default None. + The timeout for the expectation. Defaults to `None`. """ expect_attribute_to_have_value( self.loc, "data-postfix", value=value, timeout=timeout @@ -2574,7 +2574,7 @@ def slow_move(x: float, y: float, delay: float = sleep_time) -> None: y The y-coordinate. delay - The delay between each move, by default sleep_time. + The delay between each move. Defaults to `sleep_time`. """ mouse.move(x, y) time.sleep(delay) @@ -2644,11 +2644,11 @@ def _handle_center( class InputSlider(_InputSliderBase): - """Input slider control for :func:`~shiny.ui.input_slider`""" + """Input slider control for :func:`~shiny.ui.input_slider`.""" loc_irs_label: Locator """ - The Playwright `Locator` of the input slider label. + Playwright `Locator` of the input slider label. """ def __init__( @@ -2719,15 +2719,15 @@ def set( class InputSliderRange(_InputSliderBase): - """Input slider range control for :func:`~shiny.ui.input_slider_range`""" + """Input slider range control for :func:`~shiny.ui.input_slider_range`.""" loc_irs_label_from: Locator """ - The Playwright `Locator` of the input slider label for the `from` handle. + Playwright `Locator` of the input slider label for the `from` handle. """ loc_irs_label_to: Locator """ - The Playwright `Locator` of the input slider label for the `to` handle. + Playwright `Locator` of the input slider label for the `to` handle. """ def __init__( @@ -3129,19 +3129,19 @@ def __init__(self, page: Page, id: str) -> None: class InputDateRange(_WidthContainerM, _InputWithLabel): - """Input date range control for :func:`~shiny.ui.input_date_range`""" + """Input date range control for :func:`~shiny.ui.input_date_range`.""" loc_separator: Locator """ - The Playwright `Locator` of the separator between the two input elements. + Playwright `Locator` of the separator between the two input elements. """ loc_start: Locator """ - The Playwright `Locator` of the start date input element. + Playwright `Locator` of the start date input element. """ loc_end: Locator """ - The Playwright `Locator` of the end date input element. + Playwright `Locator` of the end date input element. """ date_start: _DateBase """ @@ -3438,11 +3438,11 @@ class _OutputBase: """ loc: Locator """ - The Playwright `Locator` of the output control. + Playwright `Locator` of the output control. """ page: Page """ - The Playwright `Page` of the Shiny app. + Playwright `Page` of the Shiny app. """ def __init__( @@ -3541,11 +3541,11 @@ class OutputText( _OutputInlineContainerM, _OutputTextValue, ): - """Text output control for :func:`~shiny.ui.text_output`""" + """Text output control for :func:`~shiny.ui.text_output`.""" loc: Locator """ - The Playwright `Locator` of the text output. + Playwright `Locator` of the text output. """ def __init__( @@ -3559,7 +3559,7 @@ def __init__( Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the text output. """ @@ -3578,11 +3578,11 @@ def get_value(self, *, timeout: Timeout = None) -> str: class OutputCode(_OutputTextValue): - """Code output control for :func:`~shiny.ui.code_output`""" + """Code output control for :func:`~shiny.ui.code_output`.""" loc: Locator """ - The Playwright `Locator` of the code output. + Playwright `Locator` of the code output. """ def __init__(self, page: Page, id: str) -> None: @@ -3592,7 +3592,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the code output. """ @@ -3620,11 +3620,11 @@ def expect_has_placeholder( class OutputTextVerbatim(_OutputTextValue): - """Verbatim text output control for :func:`~shiny.ui.text_output_verbatim`""" + """Verbatim text output control for :func:`~shiny.ui.text_output_verbatim`.""" loc: Locator """ - The Playwright `Locator` of the verbatim text output. + Playwright `Locator` of the verbatim text output. """ def __init__(self, page: Page, id: str) -> None: @@ -3634,7 +3634,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the verbatim text output. """ @@ -3655,7 +3655,7 @@ class _OutputImageBase(_OutputInlineContainerM, _OutputBase): loc_img: Locator """ - The Playwright `Locator` of the image. + Playwright `Locator` of the image. """ def __init__(self, page: Page, id: str, loc_classes: str = "") -> None: @@ -3665,7 +3665,7 @@ def __init__(self, page: Page, id: str, loc_classes: str = "") -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the image. loc_classes @@ -3803,7 +3803,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the image. """ @@ -3811,11 +3811,11 @@ def __init__(self, page: Page, id: str) -> None: class OutputPlot(_OutputImageBase): - """Plot output control for :func:`~shiny.ui.plot_output`""" + """Plot output control for :func:`~shiny.ui.plot_output`.""" loc: Locator """ - The Playwright `Locator` of the plot output. + Playwright `Locator` of the plot output. """ def __init__(self, page: Page, id: str) -> None: @@ -3825,7 +3825,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the plot. """ @@ -3833,7 +3833,7 @@ def __init__(self, page: Page, id: str) -> None: class OutputUi(_OutputInlineContainerM, _OutputBase): - """UI output control for :func:`~shiny.ui.ui_output`""" + """UI output control for :func:`~shiny.ui.ui_output`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -3842,7 +3842,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the UI output. """ @@ -3861,7 +3861,7 @@ def expect_text(self, text: str, *, timeout: Timeout = None) -> None: # When making selectors, use `xpath` so that direct decendents can be checked class OutputTable(_OutputBase): - """Table output control for :func:`~shiny.ui.table_output`""" + """Table output control for :func:`~shiny.ui.table_output`.""" def __init__(self, page: Page, id: str) -> None: """ @@ -3870,7 +3870,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the table. """ @@ -4012,23 +4012,23 @@ class Sidebar( _WidthLocM, _InputWithContainer, ): - """Sidebar control for func: `~shiny.ui.sidebar`""" + """Sidebar control for func: `~shiny.ui.sidebar`.""" loc_container: Locator """ - `loc_container` is the locator of the container of the input. + Playwright `Locator` for the sidebar layout. """ loc: Locator """ - The Playwright `Locator` for the sidebar. + Playwright `Locator` for the sidebar. """ loc_handle: Locator """ - The Playwright `Locator` for the handle of the sidebar. + Playwright `Locator` for the open/close handle of the sidebar. """ loc_position: Locator """ - The Playwright `Locator` for the position of the sidebar. + Playwright `Locator` for the position of the sidebar. """ def __init__(self, page: Page, id: str) -> None: @@ -4038,7 +4038,7 @@ def __init__(self, page: Page, id: str) -> None: Parameters ---------- page - The Playwright page. + Playwright `Page` of the Shiny app. id The ID of the sidebar. """ @@ -4092,7 +4092,7 @@ def expect_handle(self, exists: bool, *, timeout: Timeout = None) -> None: Parameters ---------- exists - True if the sidebar handle should exist, False otherwise. + `True` if the sidebar open/close handle should exist, `False` otherwise. timeout The maximum time to wait for the sidebar handle to appear. Defaults to `None`. """ @@ -4105,7 +4105,7 @@ def expect_open(self, open: bool, *, timeout: Timeout = None) -> None: Parameters ---------- open - True if the sidebar should be open, False otherwise. + `True` if the sidebar should be open, `False` to be closed. timeout The maximum time to wait for the sidebar to open or close. Defaults to `None`. """ @@ -4120,7 +4120,7 @@ def set(self, open: bool, *, timeout: Timeout = None) -> None: Parameters ---------- open - True if the sidebar should be open, False otherwise. + `True` to open the sidebar and `False` to close it. timeout The maximum time to wait for the sidebar to open or close. Defaults to `None`. """ @@ -4148,7 +4148,7 @@ class _CardBodyP(_InputBaseP, Protocol): loc_body: Locator """ - The Playwright `Locator` for the body element of the card control. + Playwright `Locator` for the body element of the card control. """ @@ -4183,7 +4183,7 @@ class _CardFooterLayoutP(_InputBaseP, Protocol): loc_footer: Locator """ - The Playwright `Locator` for the footer element. + Playwright `Locator` for the footer element. """ @@ -4214,68 +4214,69 @@ def expect_footer( ) -class _CardFullScreenLayoutP(_OutputBaseP, Protocol): +class _CardValueBoxFullScreenLayoutP(_OutputBaseP, Protocol): """ - Represents a card full-screen layout for the Playwright controls. + Represents a card / Value Box full-screen layout for the Playwright controls. """ loc_title: Locator """ - The Playwright `Locator` for the title element. + Playwright `Locator` for the title element. """ _loc_fullscreen: Locator """ - The Playwright `Locator` for the full-screen element. + Playwright `Locator` for the full-screen element. """ _loc_close_button: Locator """ - The Playwright `Locator` for the close button element. + Playwright `Locator` for the close button element. """ -class _CardFullScreenM: +class _CardValueBoxFullScreenM: """ - Represents a class for managing full screen functionality of a card. + Represents a class for managing full screen functionality of a Card or Value Box. """ + # TODO-karan-test: Convert `open_full_screen` and `close_full_screen` to `set_full_screen(open:bool)` def open_full_screen( - self: _CardFullScreenLayoutP, *, timeout: Timeout = None + self: _CardValueBoxFullScreenLayoutP, *, timeout: Timeout = None ) -> None: """ - Opens the card in full screen mode. + Opens the element in full screen mode. Parameters ---------- timeout - The maximum time to wait for the card to open in full screen mode. Defaults to `None`. + The maximum time to wait for full screen mode to open. Defaults to `None`. """ self.loc_title.hover(timeout=timeout) self._loc_fullscreen.wait_for(state="visible", timeout=timeout) self._loc_fullscreen.click(timeout=timeout) def close_full_screen( - self: _CardFullScreenLayoutP, *, timeout: Timeout = None + self: _CardValueBoxFullScreenLayoutP, *, timeout: Timeout = None ) -> None: """ - Closes the card from full screen mode. + Exits full screen mode. Parameters ---------- timeout - The maximum time to wait for the card to close from full screen mode. Defaults to `None`. + The maximum time to wait to wait for full screen mode to exit. Defaults to `None`. """ self._loc_close_button.click(timeout=timeout) - def expect_full_screen_open( - self: _CardFullScreenLayoutP, open: bool, *, timeout: Timeout = None + def expect_full_screen( + self: _CardValueBoxFullScreenLayoutP, open: bool, *, timeout: Timeout = None ) -> None: """ - Verifies if the card is expected to be in full screen mode. + Verifies if the full screen mode is currently open. Parameters ---------- open - True if the card is expected to be in full screen mode, False otherwise. + `True` if the item is to be in full screen mode, `False` otherwise. timeout The maximum time to wait for the verification. Defaults to `None`. """ @@ -4284,15 +4285,18 @@ def expect_full_screen_open( ) def expect_full_screen_available( - self: _CardFullScreenLayoutP, available: bool, *, timeout: Timeout = None + self: _CardValueBoxFullScreenLayoutP, + available: bool, + *, + timeout: Timeout = None, ) -> None: """ - Expects the card to be available for full screen mode. + Expects whether full screen mode is available for the element. Parameters ---------- available - True if the value box is expected to be available for full screen mode, False otherwise. + `True` if the element is expected to be available for full screen mode, False otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -4303,38 +4307,38 @@ def expect_full_screen_available( class ValueBox( _WidthLocM, - _CardFullScreenM, + _CardValueBoxFullScreenM, _InputWithContainer, ): """ - ValueBox control for :func:`~shiny.ui.value_box` + Value Box control for :func:`~shiny.ui.value_box`. """ loc: Locator """ - `Locator` for the value box's value + Playwright `Locator` for the value box's value. """ loc_showcase: Locator """ - `Locator` for the value box showcase + Playwright `Locator` for the value box showcase. """ loc_title: Locator """ - `Locator` for the value box title + Playwright `Locator` for the value box title. """ loc_body: Locator """ - `Locator` for the value box body + Playwright `Locator` for the value box body. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the ValueBox class. + Initializes a new instance of the `ValueBox` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the value box. @@ -4433,7 +4437,8 @@ def expect_body( ---------- text The expected text pattern or list of patterns/strings. - Note: If testing against multiple elements, text should be an array + + Note: If testing against multiple elements, text should be an array. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -4443,36 +4448,46 @@ def expect_body( ) -class Card(_WidthLocM, _CardFooterM, _CardBodyM, _CardFullScreenM, _InputWithContainer): +class Card( + _WidthLocM, + _CardFooterM, + _CardBodyM, + _CardValueBoxFullScreenM, + _InputWithContainer, +): """ - Card control for :func:`~shiny.ui.card` + Card control for :func:`~shiny.ui.card`. """ + loc_container: Locator + """ + Playwright `Locator` for the card container. + """ loc: Locator """ - `Locator` for the card's value + Playwright `Locator` for the card's value. """ loc_title: Locator """ - `Locator` for the card title + Playwright `Locator` for the card title. """ loc_footer: Locator """ - `Locator` for the card footer + Playwright `Locator` for the card footer. """ loc_body: Locator """ - `Locator` for the card body + Playwright `Locator` for the card body. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the Card class. + Initializes a new instance of the `Card` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the card. """ @@ -4508,8 +4523,9 @@ def expect_header( Parameters ---------- text - The expected text pattern or string - Note: None if the header is expected to not exist. + The expected text pattern or string. + + Note: `None` if the header is expected to not exist. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -4597,29 +4613,29 @@ class Accordion( _WidthLocM, _InputWithContainer, ): - """Accordion control for :func:`~shiny.ui.accordion`""" + """Accordion control for :func:`~shiny.ui.accordion`.""" loc: Locator """ - `Locator` for the accordion + Playwright `Locator` for each accordion items. """ loc_container: Locator """ - `Locator` for the accordion container - """ - loc_open: Locator - """ - `Locator` for the open accordion panel + Playwright `Locator` for the accordion container. """ + # loc_open: Locator + # """ + # `Locator` for the open accordion panel + # """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the Accordion class. + Initializes a new instance of the `Accordion` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the accordion. """ @@ -4629,14 +4645,14 @@ def __init__(self, page: Page, id: str) -> None: loc="> div.accordion-item", loc_container=f"div#{id}.accordion.shiny-bound-input", ) - self.loc_open = self.loc.locator( - # Return self - "xpath=.", - # Simple approach as position is not needed - has=page.locator( - "> div.accordion-collapse.show", - ), - ) + # self.loc_open = self.loc.locator( + # # Return self + # "xpath=.", + # # Simple approach as position is not needed + # has=page.locator( + # "> div.accordion-collapse.show", + # ), + # ) def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: """ @@ -4760,38 +4776,38 @@ class AccordionPanel( _InputWithContainer, ): """ - AccordionPanel control for :func:`~shiny.ui.accordion_panel` + AccordionPanel control for :func:`~shiny.ui.accordion_panel`. """ loc_label: Locator """ - `Locator` for the accordion panel label + Playwright `Locator` for the accordion panel's label. """ loc_icon: Locator """ - `Locator` for the accordion panel icon + Playwright `Locator` for the accordion panel's icon. """ loc_body: Locator """ - `Locator` for the accordion panel body + Playwright `Locator` for the accordion panel's body. """ loc_header: Locator """ - `Locator` for the accordion panel header - """ - loc_body_visible: Locator - """ - `Locator` for the visible accordion panel body + Playwright `Locator` for the accordion panel's header. """ + # loc_body_visible: Locator + # """ + # Playwright `Locator` for the visible accordion panel body + # """ def __init__(self, page: Page, id: str, data_value: str) -> None: """ - Initializes a new instance of the AccordionPanel class. + Initializes a new instance of the `AccordionPanel` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the accordion panel. data_value @@ -4814,7 +4830,7 @@ def __init__(self, page: Page, id: str, data_value: str) -> None: self.loc_body = self.loc.locator("> .accordion-collapse") self.loc_header = self.loc.locator("> .accordion-header") - self.loc_body_visible = self.loc.locator("> .accordion-collapse.show") + self._loc_body_visible = self.loc.locator("> .accordion-collapse.show") def expect_label(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: """ @@ -4862,7 +4878,7 @@ def expect_open(self, is_open: bool, *, timeout: Timeout = None) -> None: Parameters ---------- is_open - True if the accordion panel is expected to be open, False otherwise. + `True` if the accordion panel is expected to be open, `False` otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -4876,14 +4892,14 @@ def set(self, open: bool, *, timeout: Timeout = None) -> None: Parameters ---------- open - True if the control is expected to be open, False otherwise. + `True` to open the accordion panel, False to close it. timeout The maximum time to wait for the control to be visible and interactable. Defaults to `None`. """ self.loc.wait_for(state="visible", timeout=timeout) self.loc.scroll_into_view_if_needed(timeout=timeout) expect_not_to_have_class(self.loc_body, "collapsing", timeout=timeout) - if self.loc_body_visible.count() != int(open): + if self._loc_body_visible.count() != int(open): self.toggle(timeout=timeout) def toggle(self, *, timeout: Timeout = None) -> None: @@ -4905,15 +4921,15 @@ class _OverlayBase(_InputBase): loc_trigger: Locator """ - `loc_trigger` is the locator of the trigger element. + Playwright `Locator` for the trigger element. """ loc_overlay_body: Locator """ - `loc_overlay_body` is the locator of the overlay body. + Playwright `Locator` for the overlay body. """ loc_overlay_container: Locator """ - `loc_overlay_container` is the locator of the overlay container. + Playwright `Locator` for of the overlay container. """ def __init__( @@ -4926,16 +4942,16 @@ def __init__( overlay_selector: str, ) -> None: """ - Initializes a new instance of the OverlayBase class. + Initializes a new instance of the `OverlayBase` class. Parameters ---------- page - The Playwright `Page` object. + Playwright `Page` of the Shiny app. id The ID of the overlay. loc - The Playwright `Locator` of the overlay. + Playwright `Locator` of the overlay. overlay_name The name of the overlay. overlay_selector @@ -5007,7 +5023,7 @@ def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: Parameters ---------- active - True if the overlay is expected to be active, False otherwise. + `True` if the overlay is expected to be active, False otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -5039,29 +5055,29 @@ def expect_placement(self, value: str, *, timeout: Timeout = None) -> None: class Popover(_OverlayBase): - """Popover control for :func:`~shiny.ui.popover`""" + """Popover control for :func:`~shiny.ui.popover`.""" loc_trigger: Locator """ - `loc_trigger` is the locator of the trigger element. + Playwright `Locator` for the trigger element that opens/closes the popover. """ loc_overlay_body: Locator """ - `loc_overlay_body` is the locator of the overlay body. + Playwright `Locator` for the popover body. """ loc_overlay_container: Locator """ - `loc_overlay_container` is the locator of the overlay container. + Playwright `Locator` for the popover container. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the Popover class. + Initializes a new instance of the `Popover` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the popover. """ @@ -5080,7 +5096,7 @@ def set(self, open: bool, timeout: Timeout = None) -> None: Parameters ---------- open - True if the popover is expected to be open, False otherwise. + `True` to open the popover and `False` to close it. timeout The maximum time to wait for the popover to be visible and interactable. Defaults to `None`. """ @@ -5102,37 +5118,37 @@ def toggle(self, timeout: Timeout = None) -> None: class Tooltip(_OverlayBase): - """Tooltip control for :func:`~shiny.ui.tooltip`""" + """Tooltip control for :func:`~shiny.ui.tooltip`.""" loc_container: Locator """ - `loc_container` is the locator of the container of the input. + Playwright `Locator` for the container tooltip. """ loc: Locator """ - `loc` is the locator of the input. + Playwright `Locator` for the tooltip content. """ loc_trigger: Locator """ - `loc_trigger` is the locator of the trigger element. + Playwright `Locator` for the trigger element. """ loc_overlay_body: Locator """ - `loc_overlay_body` is the locator of the overlay body. + Playwright `Locator` for the overlay body. """ loc_overlay_container: Locator """ - `loc_overlay_container` is the locator of the overlay container. + Playwright `Locator` for the overlay container. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the Tooltip class. + Initializes a new instance of the `Tooltip` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the tooltip. """ @@ -5151,7 +5167,7 @@ def set(self, open: bool, timeout: Timeout = None) -> None: Parameters ---------- open - True if the tooltip is expected to be open, False otherwise. + `True` to open the tooltip and `False` to close it. timeout The maximum time to wait for the tooltip to be visible and interactable. Defaults to `None`. """ @@ -5294,28 +5310,28 @@ def expect_nav_titles( class NavItem(_InputWithContainer): - """NavItem control for :func:`~shiny.ui.nav_item`""" + """Navigation item control for :func:`~shiny.ui.nav_item`.""" """ - `Locator` for the content of the nav item. + Playwright `Locator` for the content of the nav item. """ loc: Locator """ - `Locator` for the nav item. + Playwright `Locator` for the nav item. """ loc_container: Locator """ - `Locator` for the nav item container. + Playwright `Locator` for the nav item container. """ def __init__(self, page: Page, id: str, data_value: str) -> None: """ - Initializes a new instance of the NavItem class. + Initializes a new instance of the `NavItem` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav item. data_value @@ -5334,8 +5350,11 @@ def __init__(self, page: Page, id: str, data_value: str) -> None: # get active content instead of assertion @property def loc_content(self) -> Locator: - """Returns the locator for the content of the nav item.""" - """Note. This requires 2 steps. Will not work if the overlay element is rapidly created during locator fetch""" + """ + Returns the locator for the content of the nav item. + + Note: This requires 2 steps. Will not work if the overlay element is rapidly created during locator fetch + """ datatab_id = self.loc_container.get_attribute("data-tabsetid") return self.page.locator( f"div.tab-content[data-tabsetid='{datatab_id}'] > div.tab-pane[data-value='{self._data_value}']" @@ -5359,7 +5378,7 @@ def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: Parameters ---------- active - True if the nav item is expected to be active, False otherwise. + `True` if the nav item is expected to be active, False otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -5380,25 +5399,25 @@ def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> Non class NavsetTab(_NavItemBase): - """NavsetTab control for :func:`~shiny.ui.navset_tab`""" + """NavsetTab control for :func:`~shiny.ui.navset_tab`.""" loc: Locator """ - `Locator` for the nav set tab. + Playwright `Locator` for the nav set tab. """ loc_container: Locator """ - `Locator` for the nav set tab container. + Playwright `Locator` for the nav set tab container. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetTab class. + Initializes a new instance of the `NavsetTab` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set tab. """ @@ -5411,16 +5430,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetPill(_NavItemBase): - """NavsetPill control for :func:`~shiny.ui.navset_pill`""" + """NavsetPill control for :func:`~shiny.ui.navset_pill`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetPill class. + Initializes a new instance of the `NavsetPill` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set pill. """ @@ -5433,16 +5452,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetUnderline(_NavItemBase): - """NavsetUnderline control for :func:`~shiny.ui.navset_underline`""" + """NavsetUnderline control for :func:`~shiny.ui.navset_underline`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetUnderline class. + Initializes a new instance of the `NavsetUnderline` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set underline. """ @@ -5455,16 +5474,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetPillList(_NavItemBase): - """NavsetPillList control for :func:`~shiny.ui.navset_pill_list`""" + """NavsetPillList control for :func:`~shiny.ui.navset_pill_list`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetPillList class. + Initializes a new instance of the `NavsetPillList` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set pill list. """ @@ -5477,16 +5496,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardTab(_NavItemBase): - """NavsetCardTab control for :func:`~shiny.ui.navset_card_tab`""" + """NavsetCardTab control for :func:`~shiny.ui.navset_card_tab`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetCardTab class. + Initializes a new instance of the `NavsetCardTab` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set card tab. """ @@ -5499,16 +5518,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardPill(_NavItemBase): - """NavsetCardPill control for :func:`~shiny.ui.navset_card_pill`""" + """NavsetCardPill control for :func:`~shiny.ui.navset_card_pill`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetCardPill class. + Initializes a new instance of the `NavsetCardPill` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set card pill. """ @@ -5521,16 +5540,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetCardUnderline(_NavItemBase): - """NavsetCardUnderline control for :func:`~shiny.ui.navset_card_underline`""" + """NavsetCardUnderline control for :func:`~shiny.ui.navset_card_underline`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetCardUnderline class. + Initializes a new instance of the `NavsetCardUnderline` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set card underline. """ @@ -5543,16 +5562,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetHidden(_NavItemBase): - """NavsetHidden control for :func:`~shiny.ui.navset_hidden`""" + """NavsetHidden control for :func:`~shiny.ui.navset_hidden`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetHidden class. + Initializes a new instance of the `NavsetHidden` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set hidden. """ @@ -5565,16 +5584,16 @@ def __init__(self, page: Page, id: str) -> None: class NavsetBar(_NavItemBase): - """NavsetBar control for :func:`~shiny.ui.navset_bar`""" + """NavsetBar control for :func:`~shiny.ui.navset_bar`.""" def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the NavsetBar class. + Initializes a new instance of the `NavsetBar` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the nav set bar. """ @@ -5588,30 +5607,34 @@ def __init__(self, page: Page, id: str) -> None: class OutputDataFrame(_InputWithContainer): """ - OutputDataFrame control for :func:`~shiny.ui.output_data_frame` + OutputDataFrame control for :func:`~shiny.ui.output_data_frame`. """ + loc_container: Locator + """ + Playwright `Locator` for the data frame container. + """ loc: Locator """ - `Locator` for the data frame + Playwright `Locator` for the data frame. """ loc_head: Locator """ - `Locator` for the data frame columns + Playwright `Locator` for the head of the data frame table. """ loc_body: Locator """ - `Locator` for the data frame rows + Playwright `Locator` for the body of the data frame table. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the OutputDataFrame class. + Initializes a new instance of the `OutputDataFrame` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the data frame. """ @@ -5701,7 +5724,7 @@ def expect_column_labels( The expected column labels. Note: None if the column labels are expected to not exist. edit - True if the data frame is in edit mode, False otherwise. + `True` if the data frame is to be in edit mode, `False` otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ @@ -5927,9 +5950,10 @@ def edit_cell( cell.click(timeout=timeout) cell.locator("> textarea").fill(text) - # TODO-karan-test: Rename to `set_column_sorting?` + # TODO-karan-test: Rename to `set_sort?` # TODO-karan-test: Add support for a list of columns # TODO-karan-test: Add support for direction + # TODO-karan-test: Add method for testing direction def set_column_sort( self, col: int, @@ -5948,9 +5972,10 @@ def set_column_sort( """ self.loc_column_label.nth(col).click(timeout=timeout) - # TODO-karan-test: Rename to `set_column_filters?` + # TODO-karan-test: Rename to `set_filter?` # TODO-karan-test: Add support for a list of columns ? If so, all other columns should be reset # TODO-karan-test: Add support for a None value reset all filters + # TODO-karan-test: Add method for testing direction def set_column_filter( self, col: int, @@ -6043,17 +6068,17 @@ def expect_cell_title( # TODO: Use mixin for dowloadlink and download button class DownloadLink(_InputActionBase): """ - DownloadLink control for :func:`~shiny.ui.download_link` + DownloadLink control for :func:`~shiny.ui.download_link`. """ def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the DownloadLink class. + Initializes a new instance of the `DownloadLink` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the download link. """ @@ -6074,12 +6099,12 @@ class DownloadButton( def __init__(self, page: Page, id: str) -> None: """ - Initializes a new instance of the DownloadButton class. + Initializes a new instance of the `DownloadButton` class. Parameters ---------- page - The Playwright page object. + Playwright `Page` of the Shiny app. id The ID of the download button. """ diff --git a/tests/playwright/shiny/components/card-input/test_card-input.py b/tests/playwright/shiny/components/card-input/test_card-input.py index 4130b6003..7b14da909 100644 --- a/tests/playwright/shiny/components/card-input/test_card-input.py +++ b/tests/playwright/shiny/components/card-input/test_card-input.py @@ -27,25 +27,25 @@ def test_card_input(page: Page, app_path: str, sel_card: str, sel_vb: str) -> No out_vb = OutputCode(page, "out_value_box") # Open and close card full screen, check input value ------ - card.expect_full_screen_open(False) + card.expect_full_screen(False) out_card.expect_value("False") card.open_full_screen() - card.expect_full_screen_open(True) + card.expect_full_screen(True) out_card.expect_value("True") card.close_full_screen() - card.expect_full_screen_open(False) + card.expect_full_screen(False) out_card.expect_value("False") # Open and close value box full screen, check input value ------ - vb.expect_full_screen_open(False) + vb.expect_full_screen(False) out_vb.expect_value("False") vb.open_full_screen() - vb.expect_full_screen_open(True) + vb.expect_full_screen(True) out_vb.expect_value("True") vb.close_full_screen() - vb.expect_full_screen_open(False) + vb.expect_full_screen(False) out_vb.expect_value("False") diff --git a/tests/playwright/shiny/components/value_box/kitchensink/test_valuebox_ks.py b/tests/playwright/shiny/components/value_box/kitchensink/test_valuebox_ks.py index f5d72e24b..16fb9b07a 100644 --- a/tests/playwright/shiny/components/value_box/kitchensink/test_valuebox_ks.py +++ b/tests/playwright/shiny/components/value_box/kitchensink/test_valuebox_ks.py @@ -60,12 +60,12 @@ def test_valuebox(page: Page, local_app: ShinyAppProc) -> None: assert get_value_box_bg_color(value_box1) == "rgb(193, 0, 0)" assert get_value_box_fg_color(value_box1) == "rgb(255, 255, 255)" value_box1.expect_full_screen_available(True) - value_box1.expect_full_screen_open(False) + value_box1.expect_full_screen(False) value_box1.open_full_screen() - value_box1.expect_full_screen_open(True) + value_box1.expect_full_screen(True) value_box1.expect_body(["Inside the fullscreen"]) value_box1.close_full_screen() - value_box1.expect_full_screen_open(False) + value_box1.expect_full_screen(False) value_box2 = ValueBox(page, "valuebox2") value_box2.expect_height(None) diff --git a/tests/playwright/shiny/components/value_box/smoke/test_valuebox.py b/tests/playwright/shiny/components/value_box/smoke/test_valuebox.py index badae5341..c2715289a 100644 --- a/tests/playwright/shiny/components/value_box/smoke/test_valuebox.py +++ b/tests/playwright/shiny/components/value_box/smoke/test_valuebox.py @@ -10,9 +10,9 @@ def test_valuebox(page: Page, local_app: ShinyAppProc, value_box_id: str) -> Non page.goto(local_app.url) value_box = ValueBox(page, value_box_id) - value_box.expect_full_screen_open(False) + value_box.expect_full_screen(False) value_box.open_full_screen() - value_box.expect_full_screen_open(True) + value_box.expect_full_screen(True) if value_box_id == "valuebox1": value_box.expect_height(None) value_box.expect_title("KPI Title") @@ -30,4 +30,4 @@ def test_valuebox(page: Page, local_app: ShinyAppProc, value_box_id: str) -> Non ) assert title_tag_name == "p" value_box.close_full_screen() - value_box.expect_full_screen_open(False) + value_box.expect_full_screen(False) diff --git a/tests/playwright/shiny/experimental/card/kitchensink/test_card_ks.py b/tests/playwright/shiny/experimental/card/kitchensink/test_card_ks.py index a16476c5e..276c9df10 100644 --- a/tests/playwright/shiny/experimental/card/kitchensink/test_card_ks.py +++ b/tests/playwright/shiny/experimental/card/kitchensink/test_card_ks.py @@ -34,11 +34,11 @@ def test_card_kitchensink(page: Page, local_app: ShinyAppProc) -> None: "\nThis is the body of a card with default height w/ fullscreen", ] ) - card.expect_full_screen_open(False) + card.expect_full_screen(False) card.open_full_screen() - card.expect_full_screen_open(True) + card.expect_full_screen(True) card.close_full_screen() - card.expect_full_screen_open(False) + card.expect_full_screen(False) card = Card(page, "card2") card.expect_max_height(None) @@ -50,7 +50,7 @@ def test_card_kitchensink(page: Page, local_app: ShinyAppProc) -> None: ["\nThis is the body without a header of a footer - No Fullscreen\n"] ) assert get_body_tag_name(card) == "p" - card.expect_full_screen_open(False) + card.expect_full_screen(False) card.expect_full_screen_available(False) card = Card(page, "card3") diff --git a/tests/playwright/shiny/experimental/card/test_card.py b/tests/playwright/shiny/experimental/card/test_card.py index 7f06948fc..cc18b137e 100644 --- a/tests/playwright/shiny/experimental/card/test_card.py +++ b/tests/playwright/shiny/experimental/card/test_card.py @@ -20,8 +20,8 @@ def test_card(page: Page, local_app: ShinyAppProc) -> None: "\nThis is still the body.\n", ] ) - card.expect_full_screen_open(False) + card.expect_full_screen(False) card.open_full_screen() - card.expect_full_screen_open(True) + card.expect_full_screen(True) card.close_full_screen() - card.expect_full_screen_open(False) + card.expect_full_screen(False) From 5ed022c157e07dc5b0c550e9bfe58ad6165de5ed Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Mon, 10 Jun 2024 11:10:35 -0400 Subject: [PATCH 09/11] Make all `expect_*(FOO)` values to be `expect_*(value)` --- shiny/playwright/controls/_controls.py | 389 +++++++++++++++---------- 1 file changed, 232 insertions(+), 157 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index a9d4981c7..0d71e4a5c 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -1,6 +1,5 @@ """Facade classes for working with Shiny inputs/outputs in Playwright""" -# TODO-barret; Make all `expect_*(FOO)` values to be `expect_*(value)` # TODO-barret; Rename `InputBase` and `InputWithContainer` to generic, not-tied-to-input names from __future__ import annotations @@ -870,7 +869,7 @@ def expect_choices( def expect_selected( self, - selected: PatternOrStr | ListPatternOrStr, + value: PatternOrStr | ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -879,20 +878,20 @@ def expect_selected( Parameters ---------- - selected + value The expected value(s) of the selected option(s). timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ # Playwright doesn't like lists of size 0 - if isinstance(selected, list) and len(selected) == 0: + if isinstance(value, list) and len(value) == 0: playwright_expect(self.loc_selected).to_have_count(0, timeout=timeout) return - if isinstance(selected, list): - self.expect.to_have_values(selected, timeout=timeout) + if isinstance(value, list): + self.expect.to_have_values(value, timeout=timeout) else: - self.expect.to_have_value(selected, timeout=timeout) + self.expect.to_have_value(value, timeout=timeout) # _MultipleDomItems.expect_locator_values_in_list( # page=self.page, @@ -939,7 +938,7 @@ def expect_choice_groups( def expect_choice_labels( self, - choice_labels: ListPatternOrStr, + value: ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -948,30 +947,30 @@ def expect_choice_labels( Parameters ---------- - choice_labels + value The expected choice labels of the input select. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ # Playwright doesn't like lists of size 0. Instead, use `None` - if len(choice_labels) == 0: + if len(value) == 0: playwright_expect(self.loc_choices).to_have_count(0, timeout=timeout) return - playwright_expect(self.loc_choices).to_have_text(choice_labels, timeout=timeout) + playwright_expect(self.loc_choices).to_have_text(value, timeout=timeout) # multiple: bool = False, - def expect_multiple(self, multiple: bool, *, timeout: Timeout = None) -> None: + def expect_multiple(self, value: bool, *, timeout: Timeout = None) -> None: """ Expect the input select to allow multiple selections. Parameters ---------- - multiple + value Whether the input select allows multiple selections. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ - _expect_multiple(self.loc, multiple, timeout=timeout) + _expect_multiple(self.loc, value, timeout=timeout) def expect_size(self, value: AttrValue, *, timeout: Timeout = None) -> None: """ @@ -1013,13 +1012,13 @@ def __init__(self, page: Page, id: str) -> None: ) # selectize: bool = False, - def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: + def expect_selectize(self, value: bool, *, timeout: Timeout = None) -> None: """ Expect the input select to be selectize. Parameters ---------- - selectize + value Whether the input select is selectize. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. @@ -1028,7 +1027,7 @@ def expect_selectize(self, selectize: bool, *, timeout: Timeout = None) -> None: _expect_class_value( self.loc, "form-select", - has_class=not selectize, + has_class=not value, timeout=timeout, ) @@ -1283,7 +1282,11 @@ def expect_label_busy(self, value: PatternOrStr, *, timeout: Timeout = None): self.expect_label_state("busy", value, timeout=timeout) def expect_label_state( - self, state: str, value: PatternOrStr, *, timeout: Timeout = None + self, + state: str, + value: PatternOrStr, + *, + timeout: Timeout = None, ): """ Expect the label of the input task button to have a specific value in a specific state. @@ -1716,7 +1719,7 @@ class _RadioButtonCheckboxGroupBase(_InputWithLabel): def expect_choice_labels( self, - labels: ListPatternOrStr, + value: ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -1725,27 +1728,27 @@ def expect_choice_labels( Parameters ---------- - labels + value The expected labels. timeout The timeout for the expectation. Defaults to `None`. """ - if len(labels) == 1: - labels_val = labels[0] + if len(value) == 1: + labels_val = value[0] else: - labels_val = labels + labels_val = value playwright_expect(self.loc_choice_labels).to_have_text( labels_val, timeout=timeout, ) - def expect_inline(self, inline: bool, *, timeout: Timeout = None) -> None: + def expect_inline(self, value: bool, *, timeout: Timeout = None) -> None: """ Expect the input to be inline. Parameters ---------- - inline + value Whether the input is inline. timeout The timeout for the expectation. Defaults to `None`. @@ -1753,7 +1756,7 @@ def expect_inline(self, inline: bool, *, timeout: Timeout = None) -> None: _expect_class_value( self.loc_container, "shiny-input-container-inline", - has_class=inline, + has_class=value, timeout=timeout, ) @@ -1865,7 +1868,7 @@ def in_selected(value: str) -> bool: def expect_choices( self, - choices: ListPatternOrStr, + value: ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -1874,7 +1877,7 @@ def expect_choices( Parameters ---------- - choices + value The expected choices. timeout The timeout for the expectation. Defaults to `None`. @@ -1884,13 +1887,13 @@ def expect_choices( loc_container=self.loc_container, el_type="input[type=checkbox]", arr_name="choices", - arr=choices, + arr=value, timeout=timeout, ) def expect_selected( self, - selected: ListPatternOrStr, + value: ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -1899,13 +1902,13 @@ def expect_selected( Parameters ---------- - selected + value The expected values of the selected checkboxes. timeout The timeout for the expectation. Defaults to `None`. """ # Playwright doesn't like lists of size 0 - if len(selected) == 0: + if len(value) == 0: playwright_expect(self.loc_selected).to_have_count(0, timeout=timeout) return @@ -1914,7 +1917,7 @@ def expect_selected( loc_container=self.loc_container, el_type="input[type=checkbox]", arr_name="selected", - arr=selected, + arr=value, timeout=timeout, is_checked=True, ) @@ -2006,7 +2009,7 @@ def set( def expect_choices( self, - choices: ListPatternOrStr, + value: ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -2015,7 +2018,7 @@ def expect_choices( Parameters ---------- - choices + value The expected choices. timeout The timeout for the expectation. Defaults to `None`. @@ -2025,13 +2028,13 @@ def expect_choices( loc_container=self.loc_container, el_type="input[type=radio]", arr_name="choices", - arr=choices, + arr=value, timeout=timeout, ) def expect_selected( self, - selected: PatternOrStr | None, + value: PatternOrStr | None, *, timeout: Timeout = None, ) -> None: @@ -2040,17 +2043,17 @@ def expect_selected( Parameters ---------- - selected + value The expected value of the selected radio button. timeout The timeout for the expectation. Defaults to `None`. """ # Playwright doesn't like lists of size 0. Instead, use `None` - if selected is None: + if value is None: playwright_expect(self.loc_selected).to_have_count(0, timeout=timeout) return - playwright_expect(self.loc_selected).to_have_value(selected, timeout=timeout) + playwright_expect(self.loc_selected).to_have_value(value, timeout=timeout) class InputFile( @@ -2157,12 +2160,22 @@ def expect_complete( expect_to_have_style(self.loc_progress, "width", "100%", timeout=timeout) # TODO-future; Test multiple file upload - def expect_multiple(self, multiple: bool, *, timeout: Timeout = None) -> None: - _expect_multiple(self.loc, multiple, timeout=timeout) + def expect_multiple(self, value: bool, *, timeout: Timeout = None) -> None: + """ + Expect the `multiple` attribute to have a specific value. + + Parameters + ---------- + value + The expected value of the `multiple` attribute. + timeout + The timeout for the expectation. Defaults to `None`. + """ + _expect_multiple(self.loc, value, timeout=timeout) def expect_accept( self, - accept: list[str] | AttrValue, + value: list[str] | AttrValue, *, timeout: Timeout = None, ) -> None: @@ -2171,21 +2184,31 @@ def expect_accept( Parameters ---------- - accept + value The expected value of the `accept` attribute. timeout The timeout for the expectation. Defaults to `None`. """ - if isinstance(accept, list): - accept = ",".join(accept) - expect_attribute_to_have_value(self.loc, "accept", accept, timeout=timeout) + if isinstance(value, list): + value = ",".join(value) + expect_attribute_to_have_value(self.loc, "accept", value, timeout=timeout) - def expect_width(self, width: StyleValue, *, timeout: Timeout = None) -> None: - expect_to_have_style(self.loc_container, "width", width, timeout=timeout) + def expect_width(self, value: StyleValue, *, timeout: Timeout = None) -> None: + """ + Expect the width of the input file to have a specific value. + + Parameters + ---------- + value + The expected value of the width. + timeout + The timeout for the expectation. Defaults to `None`. + """ + expect_to_have_style(self.loc_container, "width", value, timeout=timeout) def expect_button_label( self, - button_label: PatternOrStr, + value: PatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -2194,16 +2217,16 @@ def expect_button_label( Parameters ---------- - button_label + value The expected value of the button label. timeout The timeout for the expectation. Defaults to `None`. """ - playwright_expect(self.loc_button).to_have_text(button_label, timeout=timeout) + playwright_expect(self.loc_button).to_have_text(value, timeout=timeout) def expect_capture( self, - capture: Literal["environment", "user"] | None, + value: Literal["environment", "user"] | None, *, timeout: Timeout = None, ) -> None: @@ -2212,12 +2235,12 @@ def expect_capture( Parameters ---------- - capture + value The expected value of the `capture` attribute. timeout The timeout for the expectation. Defaults to `None`. """ - expect_attribute_to_have_value(self.loc, "capture", capture, timeout=timeout) + expect_attribute_to_have_value(self.loc, "capture", value, timeout=timeout) def expect_placeholder(self, value: AttrValue, *, timeout: Timeout = None) -> None: expect_attribute_to_have_value( @@ -3599,14 +3622,17 @@ def __init__(self, page: Page, id: str) -> None: super().__init__(page, id=id, loc=f"pre#{id}.shiny-text-output") def expect_has_placeholder( - self, placeholder: bool = False, *, timeout: Timeout = None + self, + value: bool = False, + *, + timeout: Timeout = None, ) -> None: """ Asserts that the code output has the expected placeholder. Parameters ---------- - placeholder + value Whether the code output has a placeholder. timeout The maximum time to wait for the placeholder to appear. Defaults to `None`. @@ -3614,7 +3640,7 @@ def expect_has_placeholder( _expect_class_value( self.loc, cls="noplaceholder", - has_class=not placeholder, + has_class=not value, timeout=timeout, ) @@ -3641,12 +3667,25 @@ def __init__(self, page: Page, id: str) -> None: super().__init__(page, id=id, loc=f"pre#{id}.shiny-text-output") def expect_has_placeholder( - self, placeholder: bool = False, *, timeout: Timeout = None + self, + value: bool = False, + *, + timeout: Timeout = None, ) -> None: + """ + Asserts that the verbatim text output has the expected placeholder. + + Parameters + ---------- + value + Whether the verbatim text output has a placeholder. + timeout + The maximum time to wait for the placeholder to appear. Defaults to `None`. + """ _expect_class_value( self.loc, cls="noplaceholder", - has_class=not placeholder, + has_class=not value, timeout=timeout, ) @@ -3849,14 +3888,35 @@ def __init__(self, page: Page, id: str) -> None: super().__init__(page, id=id, loc=f"#{id}") # TODO-future; Should we try verify that `recalculating` class is not present? Do this for all outputs! - def expect_empty(self, empty: bool, *, timeout: Timeout = None) -> None: - if empty: + def expect_empty(self, value: bool, *, timeout: Timeout = None) -> None: + """ + Asserts that the output is empty. + + Parameters + ---------- + value + Whether the output is empty. + timeout + The maximum time to wait for the output to be empty. Defaults to `None`. + """ + if value: self.expect.to_be_empty(timeout=timeout) else: self.expect.not_to_be_empty(timeout=timeout) - def expect_text(self, text: str, *, timeout: Timeout = None) -> None: - self.expect.to_have_text(text, timeout=timeout) + def expect_text(self, value: str, *, timeout: Timeout = None) -> None: + """ + Asserts that the output has the expected text. + + Parameters + ---------- + value + The expected text. + timeout + The maximum time to wait for the text to appear. Defaults to `None`. + """ + + self.expect.to_have_text(value, timeout=timeout) # When making selectors, use `xpath` so that direct decendents can be checked @@ -3878,7 +3938,7 @@ def __init__(self, page: Page, id: str) -> None: def expect_cell( self, - text: PatternOrStr, + value: PatternOrStr, row: int, col: int, *, @@ -3889,7 +3949,7 @@ def expect_cell( Parameters ---------- - text + value The expected text in the cell. row The row number. @@ -3904,11 +3964,11 @@ def expect_cell( self.loc.locator( f"xpath=./table/tbody/tr[{row}]/td[{col}] | ./table/tbody/tr[{row}]/th[{col}]" ) - ).to_have_text(text, timeout=timeout) + ).to_have_text(value, timeout=timeout) def expect_column_labels( self, - labels: ListPatternOrStr | None, + value: ListPatternOrStr | None, *, timeout: Timeout = None, ) -> None: @@ -3917,28 +3977,28 @@ def expect_column_labels( Parameters ---------- - labels + value The expected column labels. If None, it asserts that the table has no column labels. timeout The maximum time to wait for the column labels to appear. Defaults to `None`. """ - if isinstance(labels, list) and len(labels) == 0: - labels = None + if isinstance(value, list) and len(value) == 0: + value = None - if labels is None: + if value is None: playwright_expect( self.loc.locator("xpath=./table/thead/tr/th") ).to_have_count(0, timeout=timeout) else: playwright_expect( self.loc.locator("xpath=./table/thead/tr/th") - ).to_have_text(labels, timeout=timeout) + ).to_have_text(value, timeout=timeout) def expect_column_text( self, col: int, # Can't use `None` as we don't know how many rows exist - text: ListPatternOrStr, + value: ListPatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -3949,7 +4009,7 @@ def expect_column_text( ---------- col The column number. - text + value The expected text in the column. timeout The maximum time to wait for the text to appear. Defaults to `None`. @@ -3958,13 +4018,13 @@ def expect_column_text( playwright_expect( self.loc.locator(f"xpath=./table/tbody/tr/td[{col}]") ).to_have_text( - text, + value, timeout=timeout, ) def expect_n_col( self, - n: int, + value: int, *, timeout: Timeout = None, ) -> None: @@ -3973,7 +4033,7 @@ def expect_n_col( Parameters ---------- - n + value The expected number of columns in the table. timeout The maximum time to wait for the table to have the expected number of columns. Defaults to `None`. @@ -3982,13 +4042,13 @@ def expect_n_col( # self.loc.locator("xpath=./table/thead/tr[1]/(td|th)") self.loc.locator("xpath=./table/thead/tr[1]/td | ./table/thead/tr[1]/th") ).to_have_count( - n, + value, timeout=timeout, ) def expect_n_row( self, - n: int, + value: int, *, timeout: Timeout = None, ) -> None: @@ -3997,13 +4057,13 @@ def expect_n_row( Parameters ---------- - n + value The expected number of rows in the table. timeout The maximum time to wait for the table to have the expected number of rows. Defaults to `None`. """ playwright_expect(self.loc.locator("xpath=./table/tbody/tr")).to_have_count( - n, + value, timeout=timeout, ) @@ -4065,22 +4125,25 @@ def expect_text(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: playwright_expect(self.loc).to_have_text(value, timeout=timeout) def expect_position( - self, position: Literal["left", "right"], *, timeout: Timeout = None + self, + value: Literal["left", "right"], + *, + timeout: Timeout = None, ) -> None: """ Asserts that the sidebar is in the expected position. Parameters ---------- - position + value The expected position of the sidebar. timeout The maximum time to wait for the sidebar to appear. Defaults to `None`. """ - is_right_sidebar = position == "right" + is_right_sidebar = value == "right" _expect_class_value( self.loc_position, - f"sidebar-{position}", + f"sidebar-{value}", is_right_sidebar, timeout=timeout, ) @@ -4098,19 +4161,19 @@ def expect_handle(self, exists: bool, *, timeout: Timeout = None) -> None: """ playwright_expect(self.loc_handle).to_have_count(int(exists), timeout=timeout) - def expect_open(self, open: bool, *, timeout: Timeout = None) -> None: + def expect_open(self, value: bool, *, timeout: Timeout = None) -> None: """ Expect the sidebar to be open or closed. Parameters ---------- - open + value `True` if the sidebar should be open, `False` to be closed. timeout The maximum time to wait for the sidebar to open or close. Defaults to `None`. """ playwright_expect(self.loc_handle).to_have_attribute( - "aria-expanded", str(open).lower(), timeout=timeout + "aria-expanded", str(value).lower(), timeout=timeout ) def set(self, open: bool, *, timeout: Timeout = None) -> None: @@ -4383,7 +4446,7 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: def expect_title( self, - text: PatternOrStr, + value: PatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -4392,20 +4455,20 @@ def expect_title( Parameters ---------- - text + value The expected text pattern or string. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_title).to_have_text( - text, + value, timeout=timeout, ) def expect_value( self, - text: PatternOrStr, + value: PatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -4414,19 +4477,19 @@ def expect_value( Parameters ---------- - text + value The expected text pattern or string. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc).to_have_text( - text, + value, timeout=timeout, ) def expect_body( self, - text: PatternOrStr | list[PatternOrStr], + value: PatternOrStr | list[PatternOrStr], *, timeout: Timeout = None, ) -> None: @@ -4435,7 +4498,7 @@ def expect_body( Parameters ---------- - text + value The expected text pattern or list of patterns/strings. Note: If testing against multiple elements, text should be an array. @@ -4443,7 +4506,7 @@ def expect_body( The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_body).to_have_text( - text, + value, timeout=timeout, ) @@ -4513,7 +4576,7 @@ def __init__(self, page: Page, id: str) -> None: def expect_header( self, - text: PatternOrStr | None, + value: PatternOrStr | None, *, timeout: Timeout = None, ) -> None: @@ -4522,17 +4585,17 @@ def expect_header( Parameters ---------- - text + value The expected text pattern or string. Note: `None` if the header is expected to not exist. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ - if text is None: + if value is None: playwright_expect(self.loc_title).to_have_count(0, timeout=timeout) else: - playwright_expect(self.loc_title).to_have_text(text, timeout=timeout) + playwright_expect(self.loc_title).to_have_text(value, timeout=timeout) # def expect_body( # self, @@ -4549,7 +4612,7 @@ def expect_header( def expect_footer( self, - text: PatternOrStr | None, + value: PatternOrStr | None, *, timeout: Timeout = None, ) -> None: @@ -4558,16 +4621,16 @@ def expect_footer( Parameters ---------- - text + value The expected text pattern or string Note: None if the footer is expected to not exist. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ - if text is None: + if value is None: playwright_expect(self.loc_footer).to_have_count(0, timeout=timeout) else: - playwright_expect(self.loc_footer).to_have_text(text, timeout=timeout) + playwright_expect(self.loc_footer).to_have_text(value, timeout=timeout) def expect_max_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: """ @@ -4871,18 +4934,18 @@ def expect_icon(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: """ playwright_expect(self.loc_icon).to_have_text(value, timeout=timeout) - def expect_open(self, is_open: bool, *, timeout: Timeout = None) -> None: + def expect_open(self, value: bool, *, timeout: Timeout = None) -> None: """ Expects the accordion panel to be open or closed. Parameters ---------- - is_open + value `True` if the accordion panel is expected to be open, `False` otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ - _expect_class_value(self.loc_body, "show", is_open, timeout=timeout) + _expect_class_value(self.loc_body, "show", value, timeout=timeout) # user sends value of Open: true | false def set(self, open: bool, *, timeout: Timeout = None) -> None: @@ -5016,23 +5079,23 @@ def expect_body(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: value, timeout=timeout ) - def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: + def expect_active(self, value: bool, *, timeout: Timeout = None) -> None: """ Expects the overlay to be active or inactive. Parameters ---------- - active + value `True` if the overlay is expected to be active, False otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ - value = re.compile(r".*") if active else None + attr_value = re.compile(r".*") if value else None return expect_attribute_to_have_value( loc=self.loc_trigger, timeout=timeout, name="aria-describedby", - value=value, + value=attr_value, ) def expect_placement(self, value: str, *, timeout: Timeout = None) -> None: @@ -5371,7 +5434,7 @@ def click(self, *, timeout: Timeout = None) -> None: """ self.loc.click(timeout=timeout) - def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: + def expect_active(self, value: bool, *, timeout: Timeout = None) -> None: """ Expects the nav item to be active or inactive. @@ -5382,7 +5445,7 @@ def expect_active(self, active: bool, *, timeout: Timeout = None) -> None: timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ - _expect_class_value(self.loc, "active", active, timeout=timeout) + _expect_class_value(self.loc, "active", value, timeout=timeout) def expect_content(self, value: PatternOrStr, *, timeout: Timeout = None) -> None: """ @@ -5665,24 +5728,24 @@ def cell_locator(self, row: int, col: int) -> Locator: f"> td:nth-child({col + 1}), > th:nth-child({col + 1})" ) - def expect_n_row(self, row_number: int, *, timeout: Timeout = None): + def expect_n_row(self, value: int, *, timeout: Timeout = None): """ Expects the number of rows in the data frame. Parameters ---------- - row_number + value The expected number of rows. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_body.locator("> tr")).to_have_count( - row_number, timeout=timeout + value, timeout=timeout ) def expect_cell( self, - text: PatternOrStr, + value: PatternOrStr, *, row: int, col: int, @@ -5693,7 +5756,7 @@ def expect_cell( Parameters ---------- - text + value The expected text in the cell. row The row number of the cell. @@ -5706,12 +5769,12 @@ def expect_cell( assert_type(col, int) self._cell_scroll_if_needed(row=row, col=col, timeout=timeout) playwright_expect(self.cell_locator(row, col)).to_have_text( - text, timeout=timeout + value, timeout=timeout ) def expect_column_labels( self, - labels: ListPatternOrStr | None, + value: ListPatternOrStr | None, *, timeout: Timeout = None, ) -> None: @@ -5720,22 +5783,23 @@ def expect_column_labels( Parameters ---------- - labels + value The expected column labels. + Note: None if the column labels are expected to not exist. edit `True` if the data frame is to be in edit mode, `False` otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ - if isinstance(labels, list) and len(labels) == 0: - labels = None + if isinstance(value, list) and len(value) == 0: + value = None - if labels is None: + if value is None: playwright_expect(self.loc_column_label).to_have_count(0, timeout=timeout) else: playwright_expect(self.loc_column_label).to_have_text( - labels, timeout=timeout + value, timeout=timeout ) def _cell_scroll_if_needed(self, *, row: int, col: int, timeout: Timeout): @@ -5781,7 +5845,7 @@ def _cell_scroll_if_needed(self, *, row: int, col: int, timeout: Timeout): def expect_column_label( self, - text: ListPatternOrStr, + value: ListPatternOrStr, *, col: int, timeout: Timeout = None, @@ -5791,23 +5855,23 @@ def expect_column_label( Parameters ---------- + value + The expected text in the column. col The column number. - text - The expected text in the column. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ assert_type(col, int) # It's zero based, nth(0) selects the first element. playwright_expect(self.loc_column_label.nth(col - 1)).to_have_text( - text, + value, timeout=timeout, ) def expect_n_col( self, - n: int, + value: int, *, timeout: Timeout = None, ) -> None: @@ -5816,19 +5880,19 @@ def expect_n_col( Parameters ---------- - n + value The expected number of columns. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.loc_column_label).to_have_count( - n, + value, timeout=timeout, ) def expect_cell_class( self, - class_: str, + value: str, *, row: int, col: int, @@ -5839,24 +5903,24 @@ def expect_cell_class( Parameters ---------- + value + The expected class of the cell. row The row number of the cell. col The column number of the cell. - class_ - The expected class of the cell. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ expect_to_have_class( self.cell_locator(row=row, col=col), - class_, + value, timeout=timeout, ) def select_rows( self, - rows: list[int], + value: list[int], *, timeout: Timeout = None, ) -> None: @@ -5865,18 +5929,18 @@ def select_rows( Parameters ---------- - rows + value The list of row numbers to select. timeout The maximum time to wait for the action to complete. Defaults to `None`. """ - if len(rows) > 1: - rows = sorted(rows) + if len(value) > 1: + value = sorted(value) # check if the items in the row contain all numbers from index 0 to index -1 - if rows == list(range(rows[0], rows[-1] + 1)): + if value == list(range(value[0], value[-1] + 1)): self.page.keyboard.down("Shift") - self.cell_locator(row=rows[0], col=0).click(timeout=timeout) - self.cell_locator(row=rows[-1], col=0).click(timeout=timeout) + self.cell_locator(row=value[0], col=0).click(timeout=timeout) + self.cell_locator(row=value[-1], col=0).click(timeout=timeout) self.page.keyboard.up("Shift") else: # if operating system is MacOs use Meta (Cmd) else use Ctrl key @@ -5884,7 +5948,7 @@ def select_rows( self.page.keyboard.down("Meta") else: self.page.keyboard.down("Control") - for row in rows: + for row in value: self._cell_scroll_if_needed(row=row, col=0, timeout=timeout) self.cell_locator(row=row, col=0).click(timeout=timeout) if platform.system() == "Darwin": @@ -5892,11 +5956,11 @@ def select_rows( else: self.page.keyboard.up("Control") else: - self.cell_locator(row=rows[0], col=0).click(timeout=timeout) + self.cell_locator(row=value[0], col=0).click(timeout=timeout) def expect_class_state( self, - state: str, + value: str, *, row: int, col: int, @@ -5904,18 +5968,29 @@ def expect_class_state( ): """ Expects the state of the class in the data frame. + + Parameters + ---------- + value + The expected state of the class. + row + The row number of the cell. + col + The column number of the cell. + timeout + The maximum time to wait for the expectation to pass. Defaults to `None`. """ - if state == "ready": + if value == "ready": playwright_expect(self.cell_locator(row=row, col=col)).not_to_have_class( "cell-edit-editing", timeout=timeout ) - elif state == "editing": + elif value == "editing": self.expect_cell_class("cell-edit-editing", row=row, col=col) - elif state == "saving": + elif value == "saving": self.expect_cell_class("cell-edit-saving", row=row, col=col) - elif state == "failure": + elif value == "failure": self.expect_cell_class("cell-edit-failure", row=row, col=col) - elif state == "success": + elif value == "success": self.expect_cell_class("cell-edit-success", row=row, col=col) else: raise ValueError( @@ -6040,7 +6115,7 @@ def save_cell( def expect_cell_title( self, - message: str, + value: str, *, row: int, col: int, @@ -6051,17 +6126,17 @@ def expect_cell_title( Parameters ---------- + value + The expected validation message of the cell. row The row number of the cell. col The column number of the cell. - message - The expected validation message of the cell. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self.cell_locator(row=row, col=col)).to_have_attribute( - name="title", value=message, timeout=timeout + name="title", value=value, timeout=timeout ) From 8a8957510dad3664d9245477535a5a02c43a63e1 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Mon, 10 Jun 2024 11:23:49 -0400 Subject: [PATCH 10/11] Rename `InputBase` and `InputWithContainer` to generic, not-tied-to-input names --- shiny/playwright/controls/_controls.py | 149 +++++++++--------- .../shiny/outputs/test_output_image.py | 2 +- .../shiny/outputs/test_output_plot.py | 2 +- .../shiny/plot-sizing/test_plot_sizing.py | 2 +- 4 files changed, 78 insertions(+), 77 deletions(-) diff --git a/shiny/playwright/controls/_controls.py b/shiny/playwright/controls/_controls.py index 0d71e4a5c..a86cd721b 100644 --- a/shiny/playwright/controls/_controls.py +++ b/shiny/playwright/controls/_controls.py @@ -1,7 +1,5 @@ """Facade classes for working with Shiny inputs/outputs in Playwright""" -# TODO-barret; Rename `InputBase` and `InputWithContainer` to generic, not-tied-to-input names - from __future__ import annotations import json @@ -142,32 +140,32 @@ def _expect_multiple(loc: Locator, multiple: bool, timeout: Timeout = None) -> N ###################################################### -class _InputBaseP(Protocol): +class _UiBaseP(Protocol): id: str loc: Locator page: Page -class _InputWithContainerP(_InputBaseP, Protocol): - """A protocol class representing inputs with a container.""" +class _UiWithContainerP(_UiBaseP, Protocol): + """A protocol class representing UI with a container.""" loc_container: Locator """ - Playwright `Locator` for the container of the input. + Playwright `Locator` for the container of the UI element. """ -class _InputBase: - """A base class representing shiny UI inputs.""" +class _UiBase: + """A base class representing shiny UI components.""" # timeout: Timeout id: str """ - The browser DOM `id` of the input. + The browser DOM `id` of the UI element. """ loc: Locator """ - Playwright `Locator` of the input. + Playwright `Locator` of the UI element. """ page: Page """ @@ -196,14 +194,14 @@ def expect(self): return playwright_expect(self.loc) -class _InputWithContainer(_InputBase): +class _UiWithContainer(_UiBase): """ - A mixin class representing inputs with a container. + A mixin class representing UI with a container. """ loc_container: Locator """ - Playwright `Locator` for the container of the input. + Playwright `Locator` for the container of the UI element. """ def __init__( @@ -222,11 +220,11 @@ def __init__( page Playwright `Page` of the Shiny app. id - The id of the input. + The id of the UI element. loc - Playwright `Locator` of the input. + Playwright `Locator` of the UI element. loc_container - Playwright `Locator` of the container of the input. + Playwright `Locator` of the container of the UI element. """ loc_is_str = isinstance(loc, str) loc_container_is_str = isinstance(loc_container, str) @@ -259,12 +257,12 @@ def __init__( self.loc_container = loc_container -class _InputWithLabel(_InputWithContainer): - """A mixin class representing inputs with a label.""" +class _UiWithLabel(_UiWithContainer): + """A mixin class representing UI components with a label.""" loc_label: Locator """ - Playwright `Locator` for the label of the input. + Playwright `Locator` for the label of the UI element. """ def __init__( @@ -284,13 +282,13 @@ def __init__( page The page where the input is located. id - The id of the input. + The id of the UI element. loc - Playwright `Locator` of the input. + Playwright `Locator` of the UI element. loc_container - Playwright `Locator` of the container of the input. + Playwright `Locator` of the container of the UI element. loc_label - Playwright `Locator` of the label of the input. Defaults to `None`. + Playwright `Locator` of the label of the UI element. Defaults to `None`. """ super().__init__( page, @@ -332,7 +330,7 @@ class _WidthLocM: """ def expect_width( - self: _InputBaseP, + self: _UiBaseP, value: AttrValue, *, timeout: Timeout = None, @@ -358,7 +356,7 @@ class _WidthContainerM: """ def expect_width( - self: _InputWithContainerP, + self: _UiWithContainerP, value: AttrValue, *, timeout: Timeout = None, @@ -379,7 +377,7 @@ def expect_width( class _SetTextM: - def set(self: _InputBaseP, value: str, *, timeout: Timeout = None) -> None: + def set(self: _UiBaseP, value: str, *, timeout: Timeout = None) -> None: """ Sets the text value @@ -397,18 +395,18 @@ class _ExpectTextInputValueM: """A mixin class for text input values.""" def expect_value( - self: _InputBaseP, + self: _UiBaseP, value: PatternOrStr, *, timeout: Timeout = None, ) -> None: """ - Expect the value of the input to have a specific value. + Expect the value of the text input to have a specific value. Parameters ---------- value - The expected value of the input. + The expected value of the text input. timeout The maximum time to wait for the expectation to be fulfilled. Defaults to `None`. """ @@ -419,7 +417,7 @@ class InputNumeric( _SetTextM, _ExpectTextInputValueM, _WidthLocM, - _InputWithLabel, + _UiWithLabel, ): """Input numeric control for :func:`~shiny.ui.input_numeric`.""" @@ -501,7 +499,7 @@ class _ExpectSpellcheckAttrM: """ def expect_spellcheck( - self: _InputBaseP, + self: _UiBaseP, value: Literal["true", "false"] | None, *, timeout: Timeout = None, @@ -524,7 +522,7 @@ def expect_spellcheck( class _ExpectPlaceholderAttrM: def expect_placeholder( - self: _InputBaseP, + self: _UiBaseP, value: AttrValue, *, timeout: Timeout = None, @@ -546,7 +544,7 @@ def expect_placeholder( class _ExpectAutocompleteAttrM: def expect_autocomplete( - self: _InputBaseP, + self: _UiBaseP, value: AttrValue, *, timeout: Timeout = None, @@ -573,7 +571,7 @@ class InputText( _ExpectPlaceholderAttrM, _ExpectAutocompleteAttrM, _ExpectSpellcheckAttrM, - _InputWithLabel, + _UiWithLabel, ): """Input text control for :func:`~shiny.ui.input_text`.""" @@ -599,7 +597,7 @@ class InputPassword( _SetTextM, _ExpectTextInputValueM, _ExpectPlaceholderAttrM, - _InputWithLabel, + _UiWithLabel, ): """Input password control for :func:`~shiny.ui.input_password`.""" @@ -650,7 +648,7 @@ class InputTextArea( _ExpectPlaceholderAttrM, _ExpectAutocompleteAttrM, _ExpectSpellcheckAttrM, - _InputWithLabel, + _UiWithLabel, ): """Input text area control for :func:`~shiny.ui.input_text_area`.""" @@ -772,7 +770,7 @@ def expect_autoresize( class _InputSelectBase( _WidthLocM, - _InputWithLabel, + _UiWithLabel, ): loc_selected: Locator """ @@ -1043,7 +1041,7 @@ def __init__(self, page: Page, id: str) -> None: ) -class _InputActionBase(_InputBase): +class _InputActionBase(_UiBase): def expect_label( self, value: PatternOrStr, @@ -1105,7 +1103,7 @@ def __init__( ) -class InputDarkMode(_InputBase): +class InputDarkMode(_UiBase): """Input dark mode control for :func:`~shiny.ui.input_dark_mode`.""" def __init__( @@ -1355,7 +1353,7 @@ def __init__( class _InputCheckboxBase( _WidthContainerM, - _InputWithLabel, + _UiWithLabel, ): def __init__( self, page: Page, id: str, loc: InitLocator, loc_label: str | None @@ -1714,7 +1712,7 @@ def expect_locator_values_in_list( # TODO-barret; continue from here -class _RadioButtonCheckboxGroupBase(_InputWithLabel): +class _RadioButtonCheckboxGroupBase(_UiWithLabel): loc_choice_labels: Locator def expect_choice_labels( @@ -2058,7 +2056,7 @@ def expect_selected( class InputFile( # _ExpectPlaceholderAttrM, - _InputWithLabel, + _UiWithLabel, ): """Input file control for :func:`~shiny.ui.input_file`.""" @@ -2248,7 +2246,7 @@ def expect_placeholder(self, value: AttrValue, *, timeout: Timeout = None) -> No ) -class _InputSliderBase(_WidthLocM, _InputWithLabel): +class _InputSliderBase(_WidthLocM, _UiWithLabel): loc_irs: Locator """ @@ -2909,7 +2907,7 @@ def set( class _DateBase( _SetTextM, _WidthContainerM, - _InputWithLabel, + _UiWithLabel, ): # Due to the `language` parameter, we can't use `datetime.date` as a value type @@ -3151,7 +3149,7 @@ def __init__(self, page: Page, id: str) -> None: ) -class InputDateRange(_WidthContainerM, _InputWithLabel): +class InputDateRange(_WidthContainerM, _UiWithLabel): """Input date range control for :func:`~shiny.ui.input_date_range`.""" loc_separator: Locator @@ -3515,7 +3513,7 @@ def expect_value( class _OutputContainerP(_OutputBaseP, Protocol): def expect_container_tag( self: _OutputBaseP, - tag_name: Literal["span", "div"] | str, + value: Literal["span", "div"] | str, *, timeout: Timeout = None, ) -> None: ... @@ -3524,7 +3522,7 @@ def expect_container_tag( class _OutputContainerM: def expect_container_tag( self: _OutputBaseP, - tag_name: Literal["span", "div"] | str, + value: Literal["span", "div"] | str, *, timeout: Timeout = None, ) -> None: @@ -3533,30 +3531,33 @@ def expect_container_tag( Parameters ---------- - tag_name + value The expected container tag. timeout The maximum time to wait for the container tag to appear. Defaults to `None`. """ - loc = self.loc.locator(f"xpath=self::{tag_name}") + loc = self.loc.locator(f"xpath=self::{value}") playwright_expect(loc).to_have_count(1, timeout=timeout) class _OutputInlineContainerM(_OutputContainerM): def expect_inline( - self: _OutputContainerP, inline: bool = False, *, timeout: Timeout = None + self: _OutputContainerP, + value: bool = False, + *, + timeout: Timeout = None, ) -> None: """ Asserts that the output is inline. Parameters ---------- - inline + value Whether the output is inline. timeout The maximum time to wait for the output to appear. Defaults to `None`. """ - tag_name = "span" if inline else "div" + tag_name = "span" if value else "div" self.expect_container_tag(tag_name, timeout=timeout) @@ -4070,7 +4071,7 @@ def expect_n_row( class Sidebar( _WidthLocM, - _InputWithContainer, + _UiWithContainer, ): """Sidebar control for func: `~shiny.ui.sidebar`.""" @@ -4204,7 +4205,7 @@ def toggle(self, *, timeout: Timeout = None) -> None: self.loc_handle.click(timeout=timeout) -class _CardBodyP(_InputBaseP, Protocol): +class _CardBodyP(_UiBaseP, Protocol): """ Represents the body of a card control. """ @@ -4220,7 +4221,7 @@ class _CardBodyM: def expect_body( self: _CardBodyP, - text: PatternOrStr | list[PatternOrStr], + value: PatternOrStr | list[PatternOrStr], *, timeout: Timeout = None, ) -> None: @@ -4234,12 +4235,12 @@ def expect_body( The maximum time to wait for the text to appear. Defaults to `None`. """ playwright_expect(self.loc).to_have_text( - text, + value, timeout=timeout, ) -class _CardFooterLayoutP(_InputBaseP, Protocol): +class _CardFooterLayoutP(_UiBaseP, Protocol): """ Represents the layout of the footer in a card. """ @@ -4257,7 +4258,7 @@ class _CardFooterM: def expect_footer( self: _CardFooterLayoutP, - text: PatternOrStr, + value: PatternOrStr, *, timeout: Timeout = None, ) -> None: @@ -4266,13 +4267,13 @@ def expect_footer( Parameters ---------- - text + value The expected text in the footer section. timeout The maximum time to wait for the footer text to appear. Defaults to `None`. """ playwright_expect(self.loc_footer).to_have_text( - text, + value, timeout=timeout, ) @@ -4331,25 +4332,25 @@ def close_full_screen( self._loc_close_button.click(timeout=timeout) def expect_full_screen( - self: _CardValueBoxFullScreenLayoutP, open: bool, *, timeout: Timeout = None + self: _CardValueBoxFullScreenLayoutP, value: bool, *, timeout: Timeout = None ) -> None: """ Verifies if the full screen mode is currently open. Parameters ---------- - open + value `True` if the item is to be in full screen mode, `False` otherwise. timeout The maximum time to wait for the verification. Defaults to `None`. """ playwright_expect(self._loc_close_button).to_have_count( - int(open), timeout=timeout + int(value), timeout=timeout ) def expect_full_screen_available( self: _CardValueBoxFullScreenLayoutP, - available: bool, + value: bool, *, timeout: Timeout = None, ) -> None: @@ -4358,20 +4359,20 @@ def expect_full_screen_available( Parameters ---------- - available + value `True` if the element is expected to be available for full screen mode, False otherwise. timeout The maximum time to wait for the expectation to pass. Defaults to `None`. """ playwright_expect(self._loc_fullscreen).to_have_count( - int(available), timeout=timeout + int(value), timeout=timeout ) class ValueBox( _WidthLocM, _CardValueBoxFullScreenM, - _InputWithContainer, + _UiWithContainer, ): """ Value Box control for :func:`~shiny.ui.value_box`. @@ -4516,7 +4517,7 @@ class Card( _CardFooterM, _CardBodyM, _CardValueBoxFullScreenM, - _InputWithContainer, + _UiWithContainer, ): """ Card control for :func:`~shiny.ui.card`. @@ -4674,7 +4675,7 @@ def expect_height(self, value: StyleValue, *, timeout: Timeout = None) -> None: class Accordion( _WidthLocM, - _InputWithContainer, + _UiWithContainer, ): """Accordion control for :func:`~shiny.ui.accordion`.""" @@ -4836,7 +4837,7 @@ def accordion_panel( class AccordionPanel( _WidthLocM, - _InputWithContainer, + _UiWithContainer, ): """ AccordionPanel control for :func:`~shiny.ui.accordion_panel`. @@ -4979,7 +4980,7 @@ def toggle(self, *, timeout: Timeout = None) -> None: self.loc_header.click(timeout=timeout) -class _OverlayBase(_InputBase): +class _OverlayBase(_UiBase): """Base class for overlay controls""" loc_trigger: Locator @@ -5253,7 +5254,7 @@ def toggle(self, timeout: Timeout = None) -> None: self.loc_trigger.hover(timeout=timeout) -class _NavItemBase(_InputWithContainer): +class _NavItemBase(_UiWithContainer): """A Base mixin class for Nav and NavItem controls""" def nav_item( @@ -5372,7 +5373,7 @@ def expect_nav_titles( self.expect.to_have_text(value, timeout=timeout) -class NavItem(_InputWithContainer): +class NavItem(_UiWithContainer): """Navigation item control for :func:`~shiny.ui.nav_item`.""" """ @@ -5668,7 +5669,7 @@ def __init__(self, page: Page, id: str) -> None: ) -class OutputDataFrame(_InputWithContainer): +class OutputDataFrame(_UiWithContainer): """ OutputDataFrame control for :func:`~shiny.ui.output_data_frame`. """ diff --git a/tests/playwright/shiny/outputs/test_output_image.py b/tests/playwright/shiny/outputs/test_output_image.py index 071352a8e..f1c3c0e06 100644 --- a/tests/playwright/shiny/outputs/test_output_image.py +++ b/tests/playwright/shiny/outputs/test_output_image.py @@ -14,7 +14,7 @@ def test_output_image_kitchen(page: Page, app: ShinyAppProc) -> None: img = OutputImage(page, "image") - img.expect_inline(inline=False) + img.expect_inline(False) img.expect_img_src(re.compile(r"data:image/png;base64")) img.expect_img_height(None) diff --git a/tests/playwright/shiny/outputs/test_output_plot.py b/tests/playwright/shiny/outputs/test_output_plot.py index 67ae9664a..e2cfb59f3 100644 --- a/tests/playwright/shiny/outputs/test_output_plot.py +++ b/tests/playwright/shiny/outputs/test_output_plot.py @@ -14,7 +14,7 @@ def test_output_plot_kitchen(page: Page, app: ShinyAppProc) -> None: plot = OutputPlot(page, "p") - plot.expect_inline(inline=False) + plot.expect_inline(False) plot.expect_height("400px") plot.expect_width("100%") diff --git a/tests/playwright/shiny/plot-sizing/test_plot_sizing.py b/tests/playwright/shiny/plot-sizing/test_plot_sizing.py index cb9afc08b..ae1fa7664 100644 --- a/tests/playwright/shiny/plot-sizing/test_plot_sizing.py +++ b/tests/playwright/shiny/plot-sizing/test_plot_sizing.py @@ -41,7 +41,7 @@ def test_output_image_kitchen(page: Page, local_app: ShinyAppProc) -> None: img = OutputPlot(page, plotid) # These assertions are mostly to ensure that the plots load before we # evaluate their sizes - img.expect_inline(inline=False) + img.expect_inline(False) img.expect_img_src(re.compile(r"data:image/png;base64"), timeout=20000) rect = page.evaluate( From 5202f23de8b196997f215d4611f011f4be164762 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Mon, 10 Jun 2024 13:33:28 -0400 Subject: [PATCH 11/11] Apply suggestions from code review --- shiny/playwright/__init__.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/shiny/playwright/__init__.py b/shiny/playwright/__init__.py index 50b543353..bc6e14e21 100644 --- a/shiny/playwright/__init__.py +++ b/shiny/playwright/__init__.py @@ -6,9 +6,12 @@ " Please install it with this command:" "\n\n pip install playwright" ) +# If `pytest` is installed... try: import pytest # noqa: F401 # pyright: ignore[reportUnusedImport, reportMissingTypeStubs] + # At this point, `playwright` and `pytest` are installed. + # Try to make sure `pytest-playwright` is installed try: import pytest_playwright # noqa: F401 # pyright: ignore[reportUnusedImport, reportMissingTypeStubs]