add IsPresent Resolution.

docs/extended_api/resolutions.rst

@@ -7,8 +7,22 @@ These are the Resolutions added in ScreenPy Playwright.
 .. module:: screenpy_playwright.resolutions
 
 
+IsPresent
+---------
+
+**Aliases**:
+``Present``
+``Exists``
+``Exist``
+
+.. autoclass:: IsPresent
+    :members:
+
 IsVisible
 ---------
 
+**Aliases**:
+``Visible``
+
 .. autoclass:: IsVisible
     :members:

screenpy_playwright/resolutions/__init__.py

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

screenpy_playwright/resolutions/custom_matchers/__init__.py

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

screenpy_playwright/resolutions/custom_matchers/is_present_element.py

@@ -0,0 +1,45 @@
+"""
+A matcher that matches a present element.
+
+For example:
+
+    assert_that(driver.find_element_by_id("search"), is_present_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 IsPresentElement(BaseMatcher[Optional[Locator]]):
+    """Match a locator which finds at least 1 element."""
+
+    def _matches(self, item: Locator | None) -> bool:
+        if item is None:
+            return False
+        return item.count() > 0
+
+    def describe_to(self, description: Description) -> None:
+        """Describe the passing case."""
+        description.append_text("the element is present")
+
+    def describe_match(self, _: Locator | None, match_description: Description) -> None:
+        """Describe the matching case."""
+        match_description.append_text("it was present")
+
+    def describe_mismatch(
+        self, _: Locator | None, mismatch_description: Description
+    ) -> None:
+        """Describe the failing case."""
+        mismatch_description.append_text("was not present")
+
+
+def is_present_element() -> IsPresentElement:
+    """Match a locator which finds at least 1 element present on the page."""
+    return IsPresentElement()

screenpy_playwright/resolutions/custom_matchers/is_visible_element.py

@@ -18,7 +18,7 @@
 
 
 class IsVisibleElement(BaseMatcher[Optional[Locator]]):
-    """Matches an element whose ``is_visible`` method returns True."""
+    """Match a locator whose ``is_visible`` method returns True."""
 
     def _matches(self, item: Locator | None) -> bool:
         if item is None:
@@ -44,5 +44,5 @@ def describe_mismatch(
 
 
 def is_visible_element() -> IsVisibleElement:
-    """This matcher matches any element that is visible."""
+    """Match any locator whose described element is visible."""
     return IsVisibleElement()

screenpy_playwright/resolutions/is_present.py

@@ -0,0 +1,32 @@
+"""Matches against a present WebElement."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from screenpy import beat
+
+from .custom_matchers import is_present_element
+
+if TYPE_CHECKING:
+    from .custom_matchers.is_present_element import IsPresentElement
+
+
+class IsPresent:
+    """Match on a present element.
+
+    The element does not need to be visible, only that it exists.
+
+    Examples::
+
+        the_actor.should(See.the(Element(WELCOME_BANNER), IsPresent()))
+    """
+
+    def describe(self) -> str:
+        """Describe the Resolution's expectation."""
+        return "present"
+
+    @beat("... hoping it's present.")
+    def resolve(self) -> IsPresentElement:
+        """Produce the Matcher to make the assertion."""
+        return is_present_element()

tests/test_namespace.py

@@ -11,14 +11,18 @@ def test_screenpy_playwright() -> None:
         "Element",
         "Enter",
         "Enters",
+        "Exist",
+        "Exists",
         "GoesTo",
         "GoTo",
+        "IsPresent",
         "IsVisible",
         "NoPageError",
         "Number",
         "Open",
         "Opens",
         "PageObject",
+        "Present",
         "RefreshesThePage",
         "RefreshThePage",
         "SaveAScreenshot",
@@ -95,7 +99,11 @@ def test_questions() -> None:
 
 def test_resolutions() -> None:
     expected = [
+        "Exist",
+        "Exists",
+        "IsPresent",
         "IsVisible",
+        "Present",
         "Visible",
     ]
     assert sorted(screenpy_playwright.resolutions.__all__) == sorted(expected)

tests/test_resolutions.py

@@ -1,11 +1,45 @@
-from screenpy_playwright import IsVisible
+from screenpy_playwright import IsPresent, IsVisible
+from screenpy_playwright.resolutions.custom_matchers.is_present_element import (
+    IsPresentElement,
+)
 from screenpy_playwright.resolutions.custom_matchers.is_visible_element import (
     IsVisibleElement,
 )
 
 from .useful_mocks import get_mocked_locator
 
 
+class TestIsPresent:
+    def test_can_be_instantiated(self) -> None:
+        ip = IsPresent()
+
+        assert isinstance(ip, IsPresent)
+
+    def test_describe(self) -> None:
+        assert IsPresent().describe() == "present"
+
+    def test_resolve(self) -> None:
+        assert isinstance(IsPresent().resolve(), IsPresentElement)
+
+    def test_the_test(self) -> None:
+        single_locator = get_mocked_locator()
+        multi_locator = get_mocked_locator()
+        single_locator.count.return_value = 1
+        multi_locator.count.return_value = 1337
+
+        assert IsVisible().resolve().matches(single_locator)
+        assert IsVisible().resolve().matches(multi_locator)
+
+    def test_the_test_fails(self) -> None:
+        locator = get_mocked_locator()
+        locator.count.return_value = 0
+
+        assert not IsPresent().resolve().matches(locator)
+
+    def test_the_test_fails_for_none(self) -> None:
+        assert not IsPresent().resolve().matches(None)
+
+
 class TestIsVisible:
     def test_can_be_instantiated(self) -> None:
         iv = IsVisible()