add IsVisible Resolution.

docs/extended_api.rst

@@ -17,4 +17,5 @@ through Playwright.
    extended_api/abilities
    extended_api/actions
    extended_api/questions
+   extended_api/resolutions
    extended_api/target

docs/extended_api/resolutions.rst

@@ -0,0 +1,14 @@
+======================
+Additional Resolutions
+======================
+
+These are the Resolutions added in ScreenPy Playwright.
+
+.. module:: screenpy_playwright.resolutions
+
+
+IsVisible
+---------
+
+.. autoclass:: IsVisible
+    :members:

screenpy_playwright/__init__.py

@@ -18,8 +18,9 @@
 from .exceptions import TargetingError
 from .protocols import PageObject
 from .questions import *  # noqa: F403
+from .resolutions import *  # noqa: F403
 from .target import Target
 
 __all__ = ["Target", "TargetingError", "PageObject"]
 
-__all__ += abilities.__all__ + actions.__all__ + questions.__all__
+__all__ += abilities.__all__ + actions.__all__ + questions.__all__ + resolutions.__all__

screenpy_playwright/actions/select.py

@@ -56,7 +56,7 @@ def the_option(cls, *args: str, **kwargs: Unpack[SelectTypes]) -> Self:
         method in Playwright.
 
         Aliases:
-            - the_options
+            - ``the_options``
         """
         return cls(*args, **kwargs)
 
@@ -74,7 +74,7 @@ def from_the(self, target: Target) -> Self:
         """Specify the dropdown or multi-select field to select from.
 
         Aliases:
-            - from_
+            - ``from_``
         """
         self.target = target
         return self

screenpy_playwright/questions/attribute.py

@@ -19,7 +19,8 @@ class Attribute:
     Abilities Required:
         :class:`~screenpy_playwright.abilities.BrowseTheWebSynchronously`
 
-    Examples:
+    Examples::
+
         the_actor.should(
             See.the(
                 Attribute("aria-label").of_the(LOGIN_LINK),

screenpy_playwright/resolutions/__init__.py

@@ -0,0 +1,11 @@
+"""Resolutions provide answers to the Actor's Questions."""
+
+from .is_visible import IsVisible
+
+# Natural-language-enabling aliases
+Visible = IsVisible
+
+__all__ = [
+    "IsVisible",
+    "Visible",
+]

screenpy_playwright/resolutions/custom_matchers/__init__.py

@@ -0,0 +1,5 @@
+"""Custom matchers for ScreenPy: Playwright Resolutions."""
+
+from .is_visible_element import is_visible_element
+
+__all__ = ["is_visible_element"]

screenpy_playwright/resolutions/custom_matchers/is_visible_element.py

@@ -0,0 +1,48 @@
+"""
+A matcher that matches a visible element.
+
+For example:
+
+    assert_that(driver.find_element_by_id("search"), is_visible_element())
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from hamcrest.core.base_matcher import BaseMatcher
+from playwright.sync_api import Locator
+
+if TYPE_CHECKING:
+    from hamcrest.core.description import Description
+
+
+class IsVisibleElement(BaseMatcher[Optional[Locator]]):
+    """Matches an element whose ``is_visible`` method returns True."""
+
+    def _matches(self, item: Locator | None) -> bool:
+        if item is None:
+            return False
+        return item.is_visible()
+
+    def describe_to(self, description: Description) -> None:
+        """Describe the passing case."""
+        description.append_text("the element is visible")
+
+    def describe_match(self, _: Locator | None, match_description: Description) -> None:
+        """Describe the matching case."""
+        match_description.append_text("it was visible")
+
+    def describe_mismatch(
+        self, item: Locator | None, mismatch_description: Description
+    ) -> None:
+        """Describe the failing case."""
+        if item is None:
+            mismatch_description.append_text("was not even present")
+            return
+        mismatch_description.append_text("was not visible")
+
+
+def is_visible_element() -> IsVisibleElement:
+    """This matcher matches any element that is visible."""
+    return IsVisibleElement()

screenpy_playwright/resolutions/is_visible.py

@@ -0,0 +1,30 @@
+"""Matches against a visible WebElement."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from screenpy import beat
+
+from .custom_matchers import is_visible_element
+
+if TYPE_CHECKING:
+    from .custom_matchers.is_visible_element import IsVisibleElement
+
+
+class IsVisible:
+    """Match on a visible element.
+
+    Examples::
+
+        the_actor.should(See.the(Element(WELCOME_BANNER), IsVisible()))
+    """
+
+    def describe(self) -> str:
+        """Describe the Resolution's expectation."""
+        return "visible"
+
+    @beat("... hoping it's visible.")
+    def resolve(self) -> IsVisibleElement:
+        """Produce the Matcher to make the assertion."""
+        return is_visible_element()

tests/test_namespace.py

@@ -9,6 +9,7 @@ def test_screenpy_playwright() -> None:
         "Click",
         "Element",
         "Enter",
+        "IsVisible",
         "Number",
         "Open",
         "PageObject",
@@ -18,6 +19,7 @@ def test_screenpy_playwright() -> None:
         "Target",
         "TargetingError",
         "Text",
+        "Visible",
         "Visit",
     ]
     assert sorted(screenpy_playwright.__all__) == sorted(expected)
@@ -52,3 +54,11 @@ def test_questions() -> None:
         "Text",
     ]
     assert sorted(screenpy_playwright.questions.__all__) == sorted(expected)
+
+
+def test_resolutions() -> None:
+    expected = [
+        "IsVisible",
+        "Visible",
+    ]
+    assert sorted(screenpy_playwright.resolutions.__all__) == sorted(expected)

tests/test_resolutions.py

@@ -0,0 +1,34 @@
+from screenpy_playwright import IsVisible
+from screenpy_playwright.resolutions.custom_matchers.is_visible_element import (
+    IsVisibleElement,
+)
+
+from .useful_mocks import get_mocked_locator
+
+
+class TestIsVisible:
+    def test_can_be_instantiated(self) -> None:
+        iv = IsVisible()
+
+        assert isinstance(iv, IsVisible)
+
+    def test_describe(self) -> None:
+        assert IsVisible().describe() == "visible"
+
+    def test_resolve(self) -> None:
+        assert isinstance(IsVisible().resolve(), IsVisibleElement)
+
+    def test_the_test(self) -> None:
+        locator = get_mocked_locator()
+        locator.is_visible.return_value = True
+
+        assert IsVisible().resolve().matches(locator)
+
+    def test_the_test_fails(self) -> None:
+        locator = get_mocked_locator()
+        locator.is_visible.return_value = False
+
+        assert not IsVisible().resolve().matches(locator)
+
+    def test_the_test_fails_for_none(self) -> None:
+        assert not IsVisible().resolve().matches(None)